Files
zitadel/proto/zitadel/user/v2/user_service.proto
T
5da5ccda5c fix: correct user v2 api docs for v3 (#10112)
# Which Problems Are Solved

As documentation is published from the main branch and the releases get
created from another branch, they are not always correctly equal.

# How the Problems Are Solved

Remove the unnecessary changes in the documentation for now, and create
a second PR which can then be used to update the documentation.

# Additional Changes

Correct integration tests which also use the endpoints.

# Additional Context

Closes #10083

---------

Co-authored-by: Fabienne Bühler <[email protected]>
2025-06-25 16:53:40 +02:00

3455 lines
104 KiB
Protocol Buffer

syntax = "proto3";
package zitadel.user.v2;
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "validate/validate.proto";
import "zitadel/object/v2/object.proto";
import "zitadel/protoc_gen_zitadel/v2/options.proto";
import "zitadel/user/v2/auth.proto";
import "zitadel/user/v2/email.proto";
import "zitadel/user/v2/phone.proto";
import "zitadel/user/v2/idp.proto";
import "zitadel/user/v2/password.proto";
import "zitadel/user/v2/user.proto";
import "zitadel/user/v2/key.proto";
import "zitadel/user/v2/pat.proto";
import "zitadel/user/v2/query.proto";
import "zitadel/filter/v2/filter.proto";
option go_package = "github.com/zitadel/zitadel/pkg/grpc/user/v2;user";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "User Service";
version: "2.0";
description: "This API is intended to manage users in a ZITADEL instance.";
contact:{
name: "ZITADEL"
url: "https://zitadel.com"
email: "[email protected]"
}
license: {
name: "Apache 2.0",
url: "https://github.com/zitadel/zitadel/blob/main/LICENSING.md";
};
};
schemes: HTTPS;
schemes: HTTP;
consumes: "application/json";
consumes: "application/grpc";
produces: "application/json";
produces: "application/grpc";
consumes: "application/grpc-web+proto";
produces: "application/grpc-web+proto";
host: "$CUSTOM-DOMAIN";
base_path: "/";
external_docs: {
description: "Detailed information about ZITADEL",
url: "https://zitadel.com/docs"
}
security_definitions: {
security: {
key: "OAuth2";
value: {
type: TYPE_OAUTH2;
flow: FLOW_ACCESS_CODE;
authorization_url: "$CUSTOM-DOMAIN/oauth/v2/authorize";
token_url: "$CUSTOM-DOMAIN/oauth/v2/token";
scopes: {
scope: {
key: "openid";
value: "openid";
}
scope: {
key: "urn:zitadel:iam:org:project:id:zitadel:aud";
value: "urn:zitadel:iam:org:project:id:zitadel:aud";
}
}
}
}
}
security: {
security_requirement: {
key: "OAuth2";
value: {
scope: "openid";
scope: "urn:zitadel:iam:org:project:id:zitadel:aud";
}
}
}
responses: {
key: "400";
value: {
description: "The request is malformed.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
}
}
}
}
responses: {
key: "401";
value: {
description: "Returned when the user is not authenticated.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
}
}
}
}
responses: {
key: "403";
value: {
description: "Returned when the user does not have permission to access the resource.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
}
}
}
}
};
service UserService {
// Create a User
//
// Create a new human or machine user in the specified organization.
//
// Required permission:
// - user.write
rpc CreateUser (CreateUserRequest) returns (CreateUserResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "409"
value: {
description: "The user already exists.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
};
};
}
// Create a new human user
//
// Create/import a new user with the type human. The newly created user will get a verification email if either the email address is not marked as verified and you did not request the verification to be returned.
rpc AddHumanUser (AddHumanUserRequest) returns (AddHumanUserResponse) {
option (google.api.http) = {
post: "/v2/users/human"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "user.write"
org_field: "organization"
}
http_response: {
success_code: 200
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
// User by ID
//
// Returns the full user object (human or machine) including the profile, email, etc..
rpc GetUserByID(GetUserByIDRequest) returns (GetUserByIDResponse) {
option (google.api.http) = {
get: "/v2/users/{user_id}"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
http_response: {
success_code: 200
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Search Users
//
// Search for users. By default, we will return all users of your instance that you have permission to read. Make sure to include a limit and sorting for pagination.
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
option (google.api.http) = {
post: "/v2/users"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200";
value: {
description: "A list of all users matching the query";
};
};
responses: {
key: "400";
value: {
description: "invalid list query";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
};
};
};
}
// Change the user email
//
// Change the email address of a user. If the state is set to not verified, a verification code will be generated, which can be either returned or sent to the user by email..
rpc SetEmail (SetEmailRequest) returns (SetEmailResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/email"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Resend code to verify user email
rpc ResendEmailCode (ResendEmailCodeRequest) returns (ResendEmailCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/email/resend"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Send code to verify user email
rpc SendEmailCode (SendEmailCodeRequest) returns (SendEmailCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/email/send"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify the email
//
// Verify the email with the generated code.
rpc VerifyEmail (VerifyEmailRequest) returns (VerifyEmailResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/email/verify"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Set the user phone
//
// Set the phone number of a user. If the state is set to not verified, a verification code will be generated, which can be either returned or sent to the user by sms..
rpc SetPhone(SetPhoneRequest) returns (SetPhoneResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/phone"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Delete the user phone
//
// Delete the phone number of a user.
rpc RemovePhone(RemovePhoneRequest) returns (RemovePhoneResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/phone"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Resend code to verify user phone
rpc ResendPhoneCode (ResendPhoneCodeRequest) returns (ResendPhoneCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/phone/resend"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify the phone
//
// Verify the phone with the generated code..
rpc VerifyPhone (VerifyPhoneRequest) returns (VerifyPhoneResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/phone/verify"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Update a User
//
// Partially update an existing user.
// If you change the users email or phone, you can specify how the ownership should be verified.
// If you change the users password, you can specify if the password should be changed again on the users next login.
//
// Required permission:
// - user.write
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
}
responses: {
key: "409"
value: {
description: "The user already exists.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
};
};
}
// Update Human User
//
// Update all information from a user..
rpc UpdateHumanUser(UpdateHumanUserRequest) returns (UpdateHumanUserResponse) {
option (google.api.http) = {
put: "/v2/users/human/{user_id}"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Deactivate user
//
// The state of the user will be changed to 'deactivated'. The user will not be able to log in anymore. The endpoint returns an error if the user is already in the state 'deactivated'. Use deactivate user when the user should not be able to use the account anymore, but you still need access to the user data..
rpc DeactivateUser(DeactivateUserRequest) returns (DeactivateUserResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/deactivate"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Reactivate user
//
// Reactivate a user with the state 'deactivated'. The user will be able to log in again afterward. The endpoint returns an error if the user is not in the state 'deactivated'..
rpc ReactivateUser(ReactivateUserRequest) returns (ReactivateUserResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/reactivate"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Lock user
//
// The state of the user will be changed to 'locked'. The user will not be able to log in anymore. The endpoint returns an error if the user is already in the state 'locked'. Use this endpoint if the user should not be able to log in temporarily because of an event that happened (wrong password, etc.)..
rpc LockUser(LockUserRequest) returns (LockUserResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/lock"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Unlock user
//
// The state of the user will be changed to 'active'. The user will be able to log in again. The endpoint returns an error if the user is not in the state 'locked'.
rpc UnlockUser(UnlockUserRequest) returns (UnlockUserResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/unlock"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Delete user
//
// The state of the user will be changed to 'deleted'. The user will not be able to log in anymore. Endpoints requesting this user will return an error 'User not found..
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Start the registration of passkey for a user
//
// Start the registration of a passkey for a user, as a response the public key credential creation options are returned, which are used to verify the passkey..
rpc RegisterPasskey (RegisterPasskeyRequest) returns (RegisterPasskeyResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/passkeys"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify a passkey for a user
//
// Verify the passkey registration with the public key credential..
rpc VerifyPasskeyRegistration (VerifyPasskeyRegistrationRequest) returns (VerifyPasskeyRegistrationResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/passkeys/{passkey_id}"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Create a passkey registration link for a user
//
// Create a passkey registration link which includes a code and either return it or send it to the user..
rpc CreatePasskeyRegistrationLink (CreatePasskeyRegistrationLinkRequest) returns (CreatePasskeyRegistrationLinkResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/passkeys/registration_link"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "user.passkey.write"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// List passkeys of an user
//
// List passkeys of an user
rpc ListPasskeys (ListPasskeysRequest) returns (ListPasskeysResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/passkeys/_search"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
// Remove passkey from a user
//
// Remove passkey from a user.
rpc RemovePasskey (RemovePasskeyRequest) returns (RemovePasskeyResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/passkeys/{passkey_id}"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Start the registration of a u2f token for a user
//
// Start the registration of a u2f token for a user, as a response the public key credential creation options are returned, which are used to verify the u2f token..
rpc RegisterU2F (RegisterU2FRequest) returns (RegisterU2FResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/u2f"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify a u2f token for a user
//
// Verify the u2f token registration with the public key credential..
rpc VerifyU2FRegistration (VerifyU2FRegistrationRequest) returns (VerifyU2FRegistrationResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/u2f/{u2f_id}"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Remove u2f token from a user
//
// Remove u2f token from a user.
rpc RemoveU2F (RemoveU2FRequest) returns (RemoveU2FResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/u2f/{u2f_id}"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Remove u2f token from a user";
description: "Remove u2f token from a user"
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Start the registration of a TOTP generator for a user
//
// Start the registration of a TOTP generator for a user, as a response a secret returned, which is used to initialize a TOTP app or device..
rpc RegisterTOTP (RegisterTOTPRequest) returns (RegisterTOTPResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/totp"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify a TOTP generator for a user
//
// Verify the TOTP registration with a generated code..
rpc VerifyTOTPRegistration (VerifyTOTPRegistrationRequest) returns (VerifyTOTPRegistrationResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/totp/verify"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Remove TOTP generator from a user
//
// Remove the configured TOTP generator of a user. As only one TOTP generator per user is allowed, the user will not have TOTP as a second factor afterward.
rpc RemoveTOTP (RemoveTOTPRequest) returns (RemoveTOTPResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/totp"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Add OTP SMS for a user
//
// Add a new One-Time Password (OTP) SMS factor to the authenticated user. OTP SMS will enable the user to verify a OTP with the latest verified phone number. The phone number has to be verified to add the second factor..
rpc AddOTPSMS (AddOTPSMSRequest) returns (AddOTPSMSResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/otp_sms"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Remove One-Time Password (OTP) SMS from a user
//
// Remove the configured One-Time Password (OTP) SMS factor of a user. As only one OTP SMS per user is allowed, the user will not have OTP SMS as a second factor afterward.
rpc RemoveOTPSMS (RemoveOTPSMSRequest) returns (RemoveOTPSMSResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/otp_sms"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Add OTP Email for a user
//
// Add a new One-Time Password (OTP) Email factor to the authenticated user. OTP Email will enable the user to verify a OTP with the latest verified email. The email has to be verified to add the second factor..
rpc AddOTPEmail (AddOTPEmailRequest) returns (AddOTPEmailResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/otp_email"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Remove One-Time Password (OTP) Email from a user
//
// Remove the configured One-Time Password (OTP) Email factor of a user. As only one OTP Email per user is allowed, the user will not have OTP Email as a second factor afterward.
rpc RemoveOTPEmail (RemoveOTPEmailRequest) returns (RemoveOTPEmailResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/otp_email"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Start flow with an identity provider
//
// Start a flow with an identity provider, for external login, registration or linking..
rpc StartIdentityProviderIntent (StartIdentityProviderIntentRequest) returns (StartIdentityProviderIntentResponse) {
option (google.api.http) = {
post: "/v2/idp_intents"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
// Retrieve the information returned by the identity provider
//
// Retrieve the information returned by the identity provider for registration or updating an existing user with new information..
rpc RetrieveIdentityProviderIntent (RetrieveIdentityProviderIntentRequest) returns (RetrieveIdentityProviderIntentResponse) {
option (google.api.http) = {
post: "/v2/idp_intents/{idp_intent_id}"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "Intent ID does not exist.";
}
}
};
}
// Add link to an identity provider to an user
//
// Add link to an identity provider to an user..
rpc AddIDPLink (AddIDPLinkRequest) returns (AddIDPLinkResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/links"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// List links to an identity provider of an user
//
// List links to an identity provider of an user.
rpc ListIDPLinks (ListIDPLinksRequest) returns (ListIDPLinksResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/links/_search"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
// Remove link of an identity provider to an user
//
// Remove link of an identity provider to an user.
rpc RemoveIDPLink (RemoveIDPLinkRequest) returns (RemoveIDPLinkResponse) {
option (google.api.http) = {
delete: "/v2/users/{user_id}/links/{idp_id}/{linked_user_id}"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Request a code to reset a password
//
// Request a code to reset a password..
rpc PasswordReset (PasswordResetRequest) returns (PasswordResetResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/password_reset"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Change password
//
// Change the password of a user with either a verification code or the current password..
rpc SetPassword (SetPasswordRequest) returns (SetPasswordResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/password"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Add a Users Secret
//
// Generates a client secret for the user.
// The client id is the users username.
// If the user already has a secret, it is overwritten.
// Only users of type machine can have a secret.
//
// Required permission:
// - user.write
rpc AddSecret(AddSecretRequest) returns (AddSecretResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The secret was successfully generated.";
}
};
responses: {
key: "404"
value: {
description: "The user ID does not exist.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
};
};
}
// Remove a Users Secret
//
// Remove the current client ID and client secret from a machine user.
//
// Required permission:
// - user.write
rpc RemoveSecret(RemoveSecretRequest) returns (RemoveSecretResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The secret was either successfully removed or it didn't exist in the first place.";
}
};
};
}
// Add a Key
//
// Add a keys that can be used to securely authenticate at the Zitadel APIs using JWT profile authentication using short-lived tokens.
// Make sure you store the returned key safely, as you won't be able to read it from the Zitadel API anymore.
// Only users of type machine can have keys.
//
// Required permission:
// - user.write
rpc AddKey(AddKeyRequest) returns (AddKeyResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The key was successfully created.";
}
};
responses: {
key: "404"
value: {
description: "The user ID does not exist.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
};
};
}
// Remove a Key
//
// Remove a machine users key by the given key ID and an optionally given user ID.
//
// Required permission:
// - user.write
rpc RemoveKey(RemoveKeyRequest) returns (RemoveKeyResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The key was either successfully removed or it not found in the first place.";
}
};
};
}
// Search Keys
//
// List all matching keys. By default all keys of the instance on which the caller has permission to read the owning users are returned.
// Make sure to include a limit and sorting for pagination.
//
// Required permission:
// - user.read
rpc ListKeys(ListKeysRequest) returns (ListKeysResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200";
value: {
description: "A list of all machine user keys matching the query";
};
};
responses: {
key: "400";
value: {
description: "invalid list query";
};
};
};
}
// Add a Personal Access Token
//
// Personal access tokens (PAT) are the easiest way to authenticate to the Zitadel APIs.
// Make sure you store the returned PAT safely, as you won't be able to read it from the Zitadel API anymore.
// Only users of type machine can have personal access tokens.
//
// Required permission:
// - user.write
rpc AddPersonalAccessToken(AddPersonalAccessTokenRequest) returns (AddPersonalAccessTokenResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The personal access token was successfully created.";
}
};
responses: {
key: "404"
value: {
description: "The user ID does not exist.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
}
};
};
}
// Remove a Personal Access Token
//
// Removes a machine users personal access token by the given token ID and an optionally given user ID.
//
// Required permission:
// - user.write
rpc RemovePersonalAccessToken(RemovePersonalAccessTokenRequest) returns (RemovePersonalAccessTokenResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "The personal access token was either successfully removed or it was not found in the first place.";
}
};
};
}
// Search Personal Access Tokens
//
// List all personal access tokens. By default all personal access tokens of the instance on which the caller has permission to read the owning users are returned.
// Make sure to include a limit and sorting for pagination.
//
// Required permission:
// - user.read
rpc ListPersonalAccessTokens(ListPersonalAccessTokensRequest) returns (ListPersonalAccessTokensResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200";
value: {
description: "A list of all personal access tokens matching the query";
};
};
responses: {
key: "400";
value: {
description: "invalid list query";
};
};
};
}
// List all possible authentication methods of a user
//
// List all possible authentication methods of a user like password, passwordless, (T)OTP and more..
rpc ListAuthenticationMethodTypes (ListAuthenticationMethodTypesRequest) returns (ListAuthenticationMethodTypesResponse) {
option (google.api.http) = {
get: "/v2/users/{user_id}/authentication_methods"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
rpc ListAuthenticationFactors(ListAuthenticationFactorsRequest) returns (ListAuthenticationFactorsResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/authentication_factors/_search"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
};
}
// Create an invite code for a user
//
// Create an invite code for a user to initialize their first authentication method (password, passkeys, IdP) depending on the organization's available methods.
// If an invite code has been created previously, it's url template and application name will be used as defaults for the new code.
// The new code will overwrite the previous one and make it invalid.
rpc CreateInviteCode (CreateInviteCodeRequest) returns (CreateInviteCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/invite_code"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Resend an invite code for a user
//
// Deprecated: Use [CreateInviteCode](apis/resources/user_service_v2/user-service-create-invite-code.api.mdx) instead.
//
// Resend an invite code for a user to initialize their first authentication method (password, passkeys, IdP) depending on the organization's available methods.
// A resend is only possible if a code has been created previously and sent to the user. If there is no code or it was directly returned, an error will be returned.
rpc ResendInviteCode (ResendInviteCodeRequest) returns (ResendInviteCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/invite_code/resend"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
deprecated: true;
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// Verify an invite code for a user
//
// Verify the invite code of a user previously issued. This will set their email to a verified state and
// allow the user to set up their first authentication method (password, passkeys, IdP) depending on the organization's available methods.
rpc VerifyInviteCode (VerifyInviteCodeRequest) returns (VerifyInviteCodeResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/invite_code/verify"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
// MFA Init Skipped
//
// Update the last time the user has skipped MFA initialization. The server timestamp is used.
rpc HumanMFAInitSkipped(HumanMFAInitSkippedRequest) returns (HumanMFAInitSkippedResponse) {
option (google.api.http) = {
post: "/v2/users/{user_id}/mfa_init_skipped"
body: "*"
};
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
responses: {
key: "200"
value: {
description: "OK";
}
};
responses: {
key: "404";
value: {
description: "User ID does not exist.";
}
}
};
}
}
message AddHumanUserRequest{
reserved 3;
reserved "organisation";
// optionally set your own id unique for the user.
optional string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"d654e6ba-70a3-48ef-a95d-37c8d8a7901a\"";
}
];
// optionally set a unique username, if none is provided the email will be used.
optional string username = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"minnie-mouse\"";
}
];
zitadel.object.v2.Organization organization = 11;
SetHumanProfile profile = 4 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED
];
SetHumanEmail email = 5 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED
];
SetHumanPhone phone = 10;
repeated SetMetadataEntry metadata = 6;
oneof password_type {
Password password = 7;
HashedPassword hashed_password = 8;
}
repeated IDPLink idp_links = 9;
// An Implementation of RFC 6238 is used, with HMAC-SHA-1 and time-step of 30 seconds.
// Currently no other options are supported, and if anything different is used the validation will fail.
optional string totp_secret = 12 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"";
}
];
}
message AddHumanUserResponse {
string user_id = 1;
zitadel.object.v2.Details details = 2;
optional string email_code = 3;
optional string phone_code = 4;
}
message CreateUserRequest{
message Human {
// Set the users profile information.
SetHumanProfile profile = 1 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED
];
// Set the users email address and optionally send a verification email.
SetHumanEmail email = 2 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED
];
// Set the users phone number and optionally send a verification SMS.
optional SetHumanPhone phone = 3;
// Set the users initial password and optionally require the user to set a new password.
oneof password_type {
Password password = 4;
HashedPassword hashed_password = 5;
}
// Create the user with a list of links to identity providers.
// This can be useful in migration-scenarios.
// For example, if a user already has an account in an external identity provider or another Zitadel instance, an IDP link allows the user to authenticate as usual.
// Sessions, second factors, hardware keys registered externally are still available for authentication.
// Use the following endpoints to manage identity provider links:
// - [AddIDPLink](apis/resources/user_service_v2/user-service-add-idp-link.api.mdx)
// - [RemoveIDPLink](apis/resources/user_service_v2/user-service-remove-idp-link.api.mdx)
repeated IDPLink idp_links = 7;
// An Implementation of RFC 6238 is used, with HMAC-SHA-1 and time-step of 30 seconds.
// Currently no other options are supported, and if anything different is used the validation will fail.
optional string totp_secret = 8 [
(validate.rules).string = {min_len: 1 max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200,
example: "\"TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"";
}
];
}
message Machine {
// The machine users name is a human readable field that helps identifying the user.
string name = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200,
example: "\"Acceptance Test User\"";
}
];
// The description is a field that helps to remember the purpose of the user.
optional string description = 2 [
(validate.rules).string = {min_len: 1, max_len: 500},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 500,
example: "\"The user calls the session API in the continuous integration pipeline for acceptance tests.\"";
}
];
}
// The unique identifier of the organization the user belongs to.
string organization_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200,
example: "\"69629026806489455\"";
}
];
// The ID is a unique identifier for the user in the instance.
// If not specified, it will be generated.
// You can set your own user id that is unique within the instance.
// This is useful in migration scenarios, for example if the user already has an ID in another Zitadel system.
// If not specified, it will be generated.
// It can't be changed after creation.
optional string user_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200,
example: "\"163840776835432345\"";
}
];
// The username is a unique identifier for the user in the organization.
// If not specified, Zitadel sets the username to the email for users of type human and to the user_id for users of type machine.
// It is used to identify the user in the organization and can be used for login.
optional string username = 3 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200,
example: "\"minnie-mouse\"";
}
];
// The type of the user.
oneof user_type {
option (validate.required) = true;
// Users of type human are users that are meant to be used by a person.
// They can log in interactively using a login UI.
// By default, new users will receive a verification email and, if a phone is configured, a verification SMS.
// To make sure these messages are sent, configure and activate valid SMTP and Twilio configurations.
// Read more about your options for controlling this behaviour in the email and phone field documentations.
Human human = 4;
// Users of type machine are users that are meant to be used by a machine.
// In order to authenticate, [add a secret](apis/resources/user_service_v2/user-service-add-secret.api.mdx), [a key](apis/resources/user_service_v2/user-service-add-key.api.mdx) or [a personal access token](apis/resources/user_service_v2/user-service-add-personal-access-token.api.mdx) to the user.
// Tokens generated for new users of type machine will be of an opaque Bearer type.
// You can change the users token type to JWT by using the [management v1 service method UpdateMachine](apis/resources/mgmt/management-service-update-machine.api.mdx).
Machine machine = 5;
}
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
example: "{\"organizationId\":\"69629026806489455\",\"userId\":\"163840776835432345\",\"username\":\"minnie-mouse\",\"human\":{\"profile\":{\"givenName\":\"Minnie\",\"familyName\":\"Mouse\",\"nickName\":\"Mini\",\"displayName\":\"Minnie Mouse\",\"preferredLanguage\":\"en\",\"gender\":\"GENDER_FEMALE\"},\"email\":{\"email\":\"mini@mouse.com\",\"sendCode\":{\"urlTemplate\":\"https://example.com/email/verify?userID={{.UserID}}&code={{.Code}}&orgID={{.OrgID}}\"}},\"phone\":{\"phone\":\"+41791234567\",\"isVerified\":true},\"password\":{\"password\":\"Secr3tP4ssw0rd!\",\"changeRequired\":true},\"idpLinks\":[{\"idpId\":\"d654e6ba-70a3-48ef-a95d-37c8d8a7901a\",\"userId\":\"6516849804890468048461403518\",\"userName\":\"[email protected]\"}],\"totpSecret\":\"TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"}}";
};
}
message CreateUserResponse {
// The unique identifier of the newly created user.
string id = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"69629012906488334\"";
}
];
// The timestamp of the user creation.
google.protobuf.Timestamp creation_date = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
// The email verification code if it was requested by setting the email verification to return_code.
optional string email_code = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"XTA6BC\"";
}
];
// The phone verification code if it was requested by setting the phone verification to return_code.
optional string phone_code = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"XTA6BC\"";
}
];
}
message GetUserByIDRequest {
reserved 2;
reserved "organization";
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
description: "User ID of the user you like to get."
}
];
}
message GetUserByIDResponse {
//deprecated: details is moved into user
zitadel.object.v2.Details details = 1;
zitadel.user.v2.User user = 2;
}
message ListUsersRequest {
//list limitations and ordering
zitadel.object.v2.ListQuery query = 1;
// the field the result is sorted
zitadel.user.v2.UserFieldName sorting_column = 2;
//criteria the client is looking for
repeated zitadel.user.v2.SearchQuery queries = 3;
}
message ListUsersResponse {
zitadel.object.v2.ListDetails details = 1;
zitadel.user.v2.UserFieldName sorting_column = 2;
repeated zitadel.user.v2.User result = 3;
}
message SetEmailRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string email = 2 [
(validate.rules).string = {min_len: 1, max_len: 200, email: true},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"mini@mouse.com\"";
}
];
// if no verification is specified, an email is sent with the default url
oneof verification {
SendEmailVerificationCode send_code = 3;
ReturnEmailVerificationCode return_code = 4;
bool is_verified = 5 [(validate.rules).bool.const = true];
}
}
message SetEmailResponse{
zitadel.object.v2.Details details = 1;
// in case the verification was set to return_code, the code will be returned
optional string verification_code = 2;
}
message ResendEmailCodeRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
// if no verification is specified, an email is sent with the default url
oneof verification {
SendEmailVerificationCode send_code = 2;
ReturnEmailVerificationCode return_code = 3;
}
}
message ResendEmailCodeResponse{
zitadel.object.v2.Details details = 1;
// in case the verification was set to return_code, the code will be returned
optional string verification_code = 2;
}
message SendEmailCodeRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
// if no verification is specified, an email is sent with the default url
oneof verification {
SendEmailVerificationCode send_code = 2;
ReturnEmailVerificationCode return_code = 3;
}
}
message SendEmailCodeResponse{
zitadel.object.v2.Details details = 1;
// in case the verification was set to return_code, the code will be returned
optional string verification_code = 2;
}
message VerifyEmailRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string verification_code = 2 [
(validate.rules).string = {min_len: 1, max_len: 20},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 20;
example: "\"SKJd342k\"";
description: "\"the verification code generated during the set email request\"";
}
];
}
message VerifyEmailResponse{
zitadel.object.v2.Details details = 1;
}
message SetPhoneRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string phone = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"+41791234567\"";
}
];
// if no verification is specified, an sms is sent
oneof verification {
SendPhoneVerificationCode send_code = 3;
ReturnPhoneVerificationCode return_code = 4;
bool is_verified = 5 [(validate.rules).bool.const = true];
}
}
message SetPhoneResponse{
zitadel.object.v2.Details details = 1;
// in case the verification was set to return_code, the code will be returned
optional string verification_code = 2;
}
message RemovePhoneRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message RemovePhoneResponse{
zitadel.object.v2.Details details = 1;
}
message ResendPhoneCodeRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
// if no verification is specified, an sms is sent
oneof verification {
SendPhoneVerificationCode send_code = 3;
ReturnPhoneVerificationCode return_code = 4;
}
}
message ResendPhoneCodeResponse{
zitadel.object.v2.Details details = 1;
// in case the verification was set to return_code, the code will be returned
optional string verification_code = 2;
}
message VerifyPhoneRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string verification_code = 2 [
(validate.rules).string = {min_len: 1, max_len: 20},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 20;
example: "\"SKJd342k\"";
description: "\"the verification code generated during the set phone request\"";
}
];
}
message VerifyPhoneResponse{
zitadel.object.v2.Details details = 1;
}
message DeleteUserRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}];
}
message DeleteUserResponse {
zitadel.object.v2.Details details = 1;
}
message UpdateUserRequest{
message Human {
message Profile {
// The given name is the first name of the user.
// For example, it can be used to personalize notifications and login UIs.
optional string given_name = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"Minnie\"";
}
];
// The family name is the last name of the user.
// For example, it can be used to personalize user interfaces and notifications.
optional string family_name = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"Mouse\"";
}
];
// The nick name is the users short name.
// For example, it can be used to personalize user interfaces and notifications.
optional string nick_name = 3 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"Mini\"";
}
];
// The display name is how a user should primarily be displayed in lists.
// It can also for example be used to personalize user interfaces and notifications.
optional string display_name = 4 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"Minnie Mouse\"";
}
];
// The users preferred language is the language that systems should use to interact with the user.
// It has the format of a [BCP-47 language tag](https://datatracker.ietf.org/doc/html/rfc3066).
// It is used by Zitadel where no higher prioritized preferred language can be used.
// For example, browser settings can overwrite a users preferred_language.
// Notification messages and standard login UIs use the users preferred language if it is supported and allowed on the instance.
// Else, the default language of the instance is used.
optional string preferred_language = 5 [
(validate.rules).string = {min_len: 1, max_len: 10},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 10;
example: "\"en-US\"";
}
];
// The users gender can for example be used to personalize user interfaces and notifications.
optional Gender gender = 6 [
(validate.rules).enum = {defined_only: true},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"GENDER_FEMALE\"";
}
];
}
// Change the users profile information
optional Profile profile = 1;
// Change the users email address and/or trigger a verification email
optional SetHumanEmail email = 2;
// Change the users phone number and/or trigger a verification SMS
// To delete the users phone number, leave the phone field empty and omit the verification field.
optional SetHumanPhone phone = 3;
// Change the users password.
// You can optionally require the current password or the verification code to be correct.
optional SetPassword password = 4;
}
message Machine {
// The machine users name is a human readable field that helps identifying the user.
optional string name = 1 [
(validate.rules).string = {max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"Acceptance Test User\"";
}
];
// The description is a field that helps to remember the purpose of the user.
optional string description = 2 [
(validate.rules).string = {max_len: 500},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"The user calls the session API in the continuous integration pipeline for acceptance tests.\"";
}
];
}
// The user id is the users unique identifier in the instance.
// It can't be changed.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// Set a new username that is unique within the instance.
// Beware that active tokens and sessions are invalidated when the username is changed.
optional string username = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"minnie-mouse\"";
}
];
// Change type specific properties of the user.
oneof user_type {
Human human = 3;
Machine machine = 4;
}
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
example: "{\"username\":\"minnie-mouse\",\"human\":{\"profile\":{\"givenName\":\"Minnie\",\"familyName\":\"Mouse\",\"displayName\":\"Minnie Mouse\"},\"email\":{\"email\":\"mini@mouse.com\",\"returnCode\":{}},\"phone\":{\"phone\":\"+41791234567\",\"isVerified\":true},\"password\":{\"password\":{\"password\":\"Secr3tP4ssw0rd!\",\"changeRequired\":true},\"verificationCode\":\"SKJd342k\"},\"totpSecret\":\"TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"}}";
};
}
message UpdateUserResponse {
// The timestamp of the change of the user.
google.protobuf.Timestamp change_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2025-01-23T10:34:18.051Z\"";
}
];
// In case the email verification was set to return_code, the code will be returned
optional string email_code = 2;
// In case the phone verification was set to return_code, the code will be returned
optional string phone_code = 3;
}
message UpdateHumanUserRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"d654e6ba-70a3-48ef-a95d-37c8d8a7901a\"";
}
];
optional string username = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"minnie-mouse\"";
}
];
optional SetHumanProfile profile = 3;
optional SetHumanEmail email = 4;
optional SetHumanPhone phone = 5;
optional SetPassword password = 6;
}
message UpdateHumanUserResponse {
zitadel.object.v2.Details details = 1;
optional string email_code = 2;
optional string phone_code = 3;
}
message DeactivateUserRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}
];
}
message DeactivateUserResponse {
zitadel.object.v2.Details details = 1;
}
message ReactivateUserRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}
];
}
message ReactivateUserResponse {
zitadel.object.v2.Details details = 1;
}
message LockUserRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}
];
}
message LockUserResponse {
zitadel.object.v2.Details details = 1;
}
message UnlockUserRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}
];
}
message UnlockUserResponse {
zitadel.object.v2.Details details = 1;
}
message RegisterPasskeyRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
optional PasskeyRegistrationCode code = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "\"one time code generated by ZITADEL; required to start the passkey registration without user authentication\"";
}
];
PasskeyAuthenticator authenticator = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "\"Optionally specify the authenticator type of the passkey device (platform or cross-platform). If none is provided, both values are allowed.\"";
}
];
string domain = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "\"Domain on which the user is authenticated.\"";
}
];
}
message RegisterPasskeyResponse{
zitadel.object.v2.Details details = 1;
string passkey_id = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432705\""
}
];
google.protobuf.Struct public_key_credential_creation_options = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "Options for Credential Creation (dictionary PublicKeyCredentialCreationOptions). Generated helper methods transform the field to JSON, for use in a WebauthN client. See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialcreationoptions"
example: "{\"publicKey\":{\"attestation\":\"none\",\"authenticatorSelection\":{\"userVerification\":\"required\"},\"challenge\":\"XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ\",\"excludeCredentials\":[{\"id\":\"tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI\",\"type\":\"public-key\"}],\"pubKeyCredParams\":[{\"alg\":-7,\"type\":\"public-key\"}],\"rp\":{\"id\":\"localhost\",\"name\":\"ZITADEL\"},\"timeout\":300000,\"user\":{\"displayName\":\"Tim Mohlmann\",\"id\":\"MjE1NTk4MDAwNDY0OTk4OTQw\",\"name\":\"tim\"}}}"
}
];
}
message VerifyPasskeyRegistrationRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
string passkey_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
google.protobuf.Struct public_key_credential = 3 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "PublicKeyCredential Interface. Generated helper methods populate the field from JSON created by a WebauthN client. See also: https://www.w3.org/TR/webauthn/#publickeycredential";
example: "{\"type\":\"public-key\",\"id\":\"pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00\",\"rawId\":\"pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00\",\"response\":{\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEcwRQIgRKS3VpeE9tfExXRzkoUKnG4rQWPvtSSt4YtDGgTx32oCIQDPey-2YJ4uIg-QCM4jj6aE2U3tgMFM_RP7Efx6xRu3JGhhdXRoRGF0YVikSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFAAAAADju76085Yhmlt1CEOHkwLQAIKWsFWqxeMT8SxZnwp0ZMF1nk6yhs2m3AIvdixCNVgtNpQECAyYgASFYIMGUDSP2FAQn2MIfPMy7cyB_Y30VqixVgGULTBtFjfRiIlggjUGfQo3_-CrMmH3S-ZQkFKWKnNBQEAMkFtG-9A4zqW0\",\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiQlhXdHh0WGxJeFZZa0pHT1dVaUVmM25zby02aXZKdWw2YmNmWHdMVlFIayIsIm9yaWdpbiI6Imh0dHBzOi8vbG9jYWxob3N0OjgwODAifQ\"}}";
min_length: 55;
max_length: 1048576; //1 MB
}
];
string passkey_name = 4 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"fido key\""
}
];
}
message VerifyPasskeyRegistrationResponse{
zitadel.object.v2.Details details = 1;
}
message RegisterU2FRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
string domain = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "\"Domain on which the user is authenticated.\"";
}
];
}
message RegisterU2FResponse{
zitadel.object.v2.Details details = 1;
string u2f_id = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432705\""
}
];
google.protobuf.Struct public_key_credential_creation_options = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "Options for Credential Creation (dictionary PublicKeyCredentialCreationOptions). Generated helper methods transform the field to JSON, for use in a WebauthN client. See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialcreationoptions"
example: "{\"publicKey\":{\"attestation\":\"none\",\"authenticatorSelection\":{\"userVerification\":\"required\"},\"challenge\":\"XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ\",\"excludeCredentials\":[{\"id\":\"tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI\",\"type\":\"public-key\"}],\"pubKeyCredParams\":[{\"alg\":-7,\"type\":\"public-key\"}],\"rp\":{\"id\":\"localhost\",\"name\":\"ZITADEL\"},\"timeout\":300000,\"user\":{\"displayName\":\"Tim Mohlmann\",\"id\":\"MjE1NTk4MDAwNDY0OTk4OTQw\",\"name\":\"tim\"}}}"
}
];
}
message VerifyU2FRegistrationRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
string u2f_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
google.protobuf.Struct public_key_credential = 3 [
(validate.rules).message.required = true,
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "PublicKeyCredential Interface. Generated helper methods populate the field from JSON created by a WebauthN client. See also: https://www.w3.org/TR/webauthn/#publickeycredential";
example: "{\"type\":\"public-key\",\"id\":\"pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00\",\"rawId\":\"pawVarF4xPxLFmfCnRkwXWeTrKGzabcAi92LEI1WC00\",\"response\":{\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEcwRQIgRKS3VpeE9tfExXRzkoUKnG4rQWPvtSSt4YtDGgTx32oCIQDPey-2YJ4uIg-QCM4jj6aE2U3tgMFM_RP7Efx6xRu3JGhhdXRoRGF0YVikSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFAAAAADju76085Yhmlt1CEOHkwLQAIKWsFWqxeMT8SxZnwp0ZMF1nk6yhs2m3AIvdixCNVgtNpQECAyYgASFYIMGUDSP2FAQn2MIfPMy7cyB_Y30VqixVgGULTBtFjfRiIlggjUGfQo3_-CrMmH3S-ZQkFKWKnNBQEAMkFtG-9A4zqW0\",\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiQlhXdHh0WGxJeFZZa0pHT1dVaUVmM25zby02aXZKdWw2YmNmWHdMVlFIayIsIm9yaWdpbiI6Imh0dHBzOi8vbG9jYWxob3N0OjgwODAifQ\"}}";
min_length: 55;
max_length: 1048576; //1 MB
}
];
string token_name = 4 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"fido key\""
}
];
}
message VerifyU2FRegistrationResponse{
zitadel.object.v2.Details details = 1;
}
message RemoveU2FRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string u2f_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message RemoveU2FResponse {
zitadel.object.v2.Details details = 1;
}
message RegisterTOTPRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message RegisterTOTPResponse {
zitadel.object.v2.Details details = 1;
string uri = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"otpauth://totp/ZITADEL:[email protected]?algorithm=SHA1&digits=6&issuer=ZITADEL&period=30&secret=TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"";
}
];
string secret = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"TJOPWSDYILLHXFV4MLKNNJOWFG7VSDCK\"";
}
];
}
message VerifyTOTPRegistrationRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
string code = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "Code generated by TOTP app or device"
example: "\"123456\"";
}
];
}
message VerifyTOTPRegistrationResponse {
zitadel.object.v2.Details details = 1;
}
message RemoveTOTPRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message RemoveTOTPResponse {
zitadel.object.v2.Details details = 1;
}
message AddOTPSMSRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message AddOTPSMSResponse {
zitadel.object.v2.Details details = 1;
}
message RemoveOTPSMSRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message RemoveOTPSMSResponse {
zitadel.object.v2.Details details = 1;
}
message AddOTPEmailRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message AddOTPEmailResponse {
zitadel.object.v2.Details details = 1;
}
message RemoveOTPEmailRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
}
message RemoveOTPEmailResponse {
zitadel.object.v2.Details details = 1;
}
message CreatePasskeyRegistrationLinkRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
// if no medium is specified, an email is sent with the default url
oneof medium {
SendPasskeyRegistrationLink send_link = 2;
ReturnPasskeyRegistrationCode return_code = 3;
}
}
message CreatePasskeyRegistrationLinkResponse{
zitadel.object.v2.Details details = 1;
// in case the medium was set to return_code, the code will be returned
optional PasskeyRegistrationCode code = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "\"one time code generated by ZITADEL; required to start the passkey registration without user authentication\"";
}
];
}
message ListPasskeysRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message ListPasskeysResponse {
zitadel.object.v2.ListDetails details = 1;
repeated Passkey result = 2;
}
message RemovePasskeyRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string passkey_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message RemovePasskeyResponse {
zitadel.object.v2.Details details = 1;
}
message StartIdentityProviderIntentRequest{
string idp_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "ID for existing identity provider"
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
oneof content {
RedirectURLs urls = 2;
LDAPCredentials ldap = 3;
}
}
message StartIdentityProviderIntentResponse{
zitadel.object.v2.Details details = 1;
oneof next_step {
string auth_url = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "URL to which the client should redirect"
example: "\"https://accounts.google.com/o/oauth2/v2/auth?client_id=clientID&callback=https%3A%2F%2Fzitadel.cloud%2Fidps%2Fcallback\"";
}
];
IDPIntent idp_intent = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "IDP Intent information"
}
];
bytes post_form = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "POST call information"
}
];
}
}
message RetrieveIdentityProviderIntentRequest{
string idp_intent_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "ID of the idp intent, previously returned on the success response of the IDP callback"
min_length: 1;
max_length: 200;
example: "\"163840776835432705\"";
}
];
string idp_intent_token = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "token of the idp intent, previously returned on the success response of the IDP callback"
min_length: 1;
max_length: 200;
example: "\"SJKL3ioIDpo342ioqw98fjp3sdf32wahb=\"";
}
];
}
message RetrieveIdentityProviderIntentResponse{
zitadel.object.v2.Details details = 1;
IDPInformation idp_information = 2;
string user_id = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "ID of the user in ZITADEL if external user is linked"
example: "\"163840776835432345\"";
}
];
AddHumanUserRequest add_human_user = 4;
}
message AddIDPLinkRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
IDPLink idp_link = 2;
}
message AddIDPLinkResponse {
zitadel.object.v2.Details details = 1;
}
message ListIDPLinksRequest{
string user_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
//list limitations and ordering
zitadel.object.v2.ListQuery query = 2;
}
message ListIDPLinksResponse{
zitadel.object.v2.ListDetails details = 1;
repeated IDPLink result = 2;
}
message RemoveIDPLinkRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string idp_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string linked_user_id = 3 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message RemoveIDPLinkResponse {
zitadel.object.v2.Details details = 1;
}
message PasswordResetRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
// if no medium is specified, an email is sent with the default url
oneof medium {
SendPasswordResetLink send_link = 2;
ReturnPasswordResetCode return_code = 3;
}
}
message PasswordResetResponse{
zitadel.object.v2.Details details = 1;
// in case the medium was set to return_code, the code will be returned
optional string verification_code = 2;
}
message SetPasswordRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
Password new_password = 2;
// if neither, the current password must be provided nor a verification code generated by the PasswordReset is provided,
// the user must be granted permission to set a password
oneof verification {
string current_password = 3 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"Secr3tP4ssw0rd!\"";
}
];
string verification_code = 4 [
(validate.rules).string = {min_len: 1, max_len: 20},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 20;
example: "\"SKJd342k\"";
description: "\"the verification code generated during password reset request\"";
}
];
}
}
message SetPasswordResponse{
zitadel.object.v2.Details details = 1;
}
message ListAuthenticationMethodTypesRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
optional DomainQuery domain_query = 2;
}
message DomainQuery {
// List also auth method types without domain information like passkey and U2F added through V1 APIs / Login UI.
bool include_without_domain = 1;
// List only auth methods with specific domain.
string domain = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"example.com\"";
}
];
}
message ListAuthenticationMethodTypesResponse{
zitadel.object.v2.ListDetails details = 1;
repeated AuthenticationMethodType auth_method_types = 2;
}
enum AuthenticationMethodType {
AUTHENTICATION_METHOD_TYPE_UNSPECIFIED = 0;
AUTHENTICATION_METHOD_TYPE_PASSWORD = 1;
AUTHENTICATION_METHOD_TYPE_PASSKEY = 2;
AUTHENTICATION_METHOD_TYPE_IDP = 3;
AUTHENTICATION_METHOD_TYPE_TOTP = 4;
AUTHENTICATION_METHOD_TYPE_U2F = 5;
AUTHENTICATION_METHOD_TYPE_OTP_SMS = 6;
AUTHENTICATION_METHOD_TYPE_OTP_EMAIL = 7;
}
message ListAuthenticationFactorsRequest{
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
repeated AuthFactors auth_factors = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "Specify the Auth Factors you are interested in"
default: "All Auth Factors"
}
];
repeated AuthFactorState states = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "Specify the state of the Auth Factors"
default: "Auth Factors that are ready"
}
];
}
enum AuthFactors {
OTP = 0;
OTP_SMS = 1;
OTP_EMAIL = 2;
U2F = 3;
}
message ListAuthenticationFactorsResponse {
repeated zitadel.user.v2.AuthFactor result = 1;
}
message CreateInviteCodeRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
// if no verification is specified, an email is sent with the default url and application name (ZITADEL)
oneof verification {
SendInviteCode send_code = 2;
ReturnInviteCode return_code = 3;
}
}
message CreateInviteCodeResponse {
zitadel.object.v2.Details details = 1;
// The invite code is returned if the verification was set to return_code.
optional string invite_code = 2;
}
message ResendInviteCodeRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
}
message ResendInviteCodeResponse {
zitadel.object.v2.Details details = 1;
}
message VerifyInviteCodeRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629026806489455\"";
}
];
string verification_code = 2 [
(validate.rules).string = {min_len: 1, max_len: 20},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 20;
example: "\"SKJd342k\"";
description: "\"the verification code generated during the invite code request\"";
}
];
}
message VerifyInviteCodeResponse {
zitadel.object.v2.Details details = 1;
}
message HumanMFAInitSkippedRequest {
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"69629012906488334\"";
}
];
}
message HumanMFAInitSkippedResponse {
zitadel.object.v2.Details details = 1;
}
message AddSecretRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432345\"";
}
];
}
message AddSecretResponse {
// The timestamp of the secret creation.
google.protobuf.Timestamp creation_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
// The client secret.
// Store this secret in a secure place.
// It is not possible to retrieve it again.
string client_secret = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"WoYLHB23HAZaCSxeMJGEzbu8urHICVdFp2IegVr6Q5U4lZHKAtRvmaalNDWfCuHV\"";
}
];
}
message RemoveSecretRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432345\"";
}
];
}
message RemoveSecretResponse {
// The timestamp of the secret deletion.
google.protobuf.Timestamp deletion_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message AddKeyRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// The date the key will expire and no logins will be possible anymore.
google.protobuf.Timestamp expiration_date = 2 [
(validate.rules).timestamp.required = true,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2519-04-01T08:45:00.000000Z\"";
}
];
// Optionally provide a public key of your own generated RSA private key.
bytes public_key = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1...\"";
}
];
}
message AddKeyResponse {
// The timestamp of the key creation.
google.protobuf.Timestamp creation_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
// The keys ID.
string key_id = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432345\"";
}
];
// The key which is usable to authenticate against the API.
bytes key_content = 3;
}
message RemoveKeyRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// The keys ID.
string key_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
}
message RemoveKeyResponse {
// The timestamp of the key deletion.
google.protobuf.Timestamp deletion_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message ListKeysRequest {
// List limitations and ordering.
optional zitadel.filter.v2.PaginationRequest pagination = 1;
// The field the result is sorted by. The default is the creation date. Beware that if you change this, your result pagination might be inconsistent.
optional KeyFieldName sorting_column = 2 [
(validate.rules).enum = {defined_only: true},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
default: "\"KEY_FIELD_NAME_CREATED_DATE\""
}
];
// Define the criteria to query for.
repeated KeysSearchFilter filters = 3;
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
example: "{\"pagination\":{\"offset\":0,\"limit\":10,\"asc\":false},\"sortingColumn\":\"KEY_FIELD_NAME_CREATED_DATE\",\"filters\":[{\"andFilter\":{\"filters\":[{\"organizationIdFilter\":{\"organizationId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}},{\"notFilter\":{\"filter\":{\"userIdFilter\":{\"userId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}}}},{\"orFilter\":{\"filters\":[{\"keyIdFilter\":{\"keyId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}},{\"keyIdFilter\":{\"keyId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}}]}}]}}]}";
};
}
message ListKeysResponse {
zitadel.filter.v2.PaginationResponse pagination = 1;
repeated Key result = 2;
}
message AddPersonalAccessTokenRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// The timestamp when the token will expire.
google.protobuf.Timestamp expiration_date = 2 [
(validate.rules).timestamp.required = true,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2519-04-01T08:45:00.000000Z\"";
}
];
}
message AddPersonalAccessTokenResponse {
// The timestamp of the personal access token creation.
google.protobuf.Timestamp creation_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
// The tokens ID.
string token_id = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"163840776835432345\"";
}
];
// The personal access token that can be used to authenticate against the API
string token = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"";
}
];
}
message RemovePersonalAccessTokenRequest {
// The users resource ID.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// The tokens ID.
string token_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
}
message RemovePersonalAccessTokenResponse {
// The timestamp of the personal access token deletion.
google.protobuf.Timestamp deletion_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message ListPersonalAccessTokensRequest {
// List limitations and ordering.
optional zitadel.filter.v2.PaginationRequest pagination = 1;
// The field the result is sorted by. The default is the creation date. Beware that if you change this, your result pagination might be inconsistent.
optional PersonalAccessTokenFieldName sorting_column = 2 [
(validate.rules).enum = {defined_only: true},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
default: "\"PERSONAL_ACCESS_TOKEN_FIELD_NAME_CREATED_DATE\""
}
];
// Define the criteria to query for.
repeated PersonalAccessTokensSearchFilter filters = 3;
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
example: "{\"pagination\":{\"offset\":0,\"limit\":10,\"asc\":false},\"sortingColumn\":\"PERSONAL_ACCESS_TOKEN_FIELD_NAME_CREATED_DATE\",\"filters\":[{\"andFilter\":{\"filters\":[{\"organizationIdFilter\":{\"organizationId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}},{\"notFilter\":{\"filter\":{\"userIdFilter\":{\"userId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}}}},{\"orFilter\":{\"filters\":[{\"personalAccessTokenIdFilter\":{\"personalAccessTokenId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}},{\"personalAccessTokenIdFilter\":{\"personalAccessTokenId\":\"163840776835432345\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}}]}}]}}]}";
};
}
message ListPersonalAccessTokensResponse {
zitadel.filter.v2.PaginationResponse pagination = 1;
repeated PersonalAccessToken result = 2;
}