Skip to main content

zitadel/auth.proto

This document reflects the state from API 1.0 (available from 20.04.2021)

AuthService

Healthz

rpc Healthz(HealthzRequest) HealthzResponse

GET: /healthz

GetSupportedLanguages

rpc GetSupportedLanguages(GetSupportedLanguagesRequest) GetSupportedLanguagesResponse

Returns the default languages

GET: /languages

GetMyUser

rpc GetMyUser(GetMyUserRequest) GetMyUserResponse

Returns my full blown user

GET: /users/me

RemoveMyUser

rpc RemoveMyUser(RemoveMyUserRequest) RemoveMyUserResponse

Changes the user state to deleted

DELETE: /users/me

ListMyUserChanges

rpc ListMyUserChanges(ListMyUserChangesRequest) ListMyUserChangesResponse

Returns the history of the authorized user (each event)

POST: /users/me/changes/_search

ListMyUserSessions

rpc ListMyUserSessions(ListMyUserSessionsRequest) ListMyUserSessionsResponse

Returns the user sessions of the authorized user of the current useragent

POST: /users/me/sessions/_search

ListMyMetadata

rpc ListMyMetadata(ListMyMetadataRequest) ListMyMetadataResponse

Returns the user metadata of the authorized user

POST: /users/me/metadata/_search

GetMyMetadata

rpc GetMyMetadata(GetMyMetadataRequest) GetMyMetadataResponse

Returns the user metadata by key of the authorized user

GET: /users/me/metadata/{key}

ListMyRefreshTokens

rpc ListMyRefreshTokens(ListMyRefreshTokensRequest) ListMyRefreshTokensResponse

Returns the refresh tokens of the authorized user

POST: /users/me/tokens/refresh/_search

RevokeMyRefreshToken

rpc RevokeMyRefreshToken(RevokeMyRefreshTokenRequest) RevokeMyRefreshTokenResponse

Revokes a single refresh token of the authorized user by its (token) id

DELETE: /users/me/tokens/refresh/{id}

RevokeAllMyRefreshTokens

rpc RevokeAllMyRefreshTokens(RevokeAllMyRefreshTokensRequest) RevokeAllMyRefreshTokensResponse

Revokes all refresh tokens of the authorized user

POST: /users/me/tokens/refresh/_revoke_all

UpdateMyUserName

rpc UpdateMyUserName(UpdateMyUserNameRequest) UpdateMyUserNameResponse

Change the user name of the authorize user

PUT: /users/me/username

GetMyPasswordComplexityPolicy

rpc GetMyPasswordComplexityPolicy(GetMyPasswordComplexityPolicyRequest) GetMyPasswordComplexityPolicyResponse

Returns the password complexity policy of my organisation This policy defines how the password should look

GET: /policies/passwords/complexity

UpdateMyPassword

rpc UpdateMyPassword(UpdateMyPasswordRequest) UpdateMyPasswordResponse

Change the password of the authorized user

PUT: /users/me/password

GetMyProfile

rpc GetMyProfile(GetMyProfileRequest) GetMyProfileResponse

Returns the profile information of the authorized user

GET: /users/me/profile

UpdateMyProfile

rpc UpdateMyProfile(UpdateMyProfileRequest) UpdateMyProfileResponse

Changes the profile information of the authorized user

PUT: /users/me/profile

GetMyEmail

rpc GetMyEmail(GetMyEmailRequest) GetMyEmailResponse

Returns the email address of the authorized user

GET: /users/me/email

SetMyEmail

rpc SetMyEmail(SetMyEmailRequest) SetMyEmailResponse

Changes the email address of the authorized user An email is sent to the given address, to verify it

PUT: /users/me/email

VerifyMyEmail

rpc VerifyMyEmail(VerifyMyEmailRequest) VerifyMyEmailResponse

Sets the email address to verified

POST: /users/me/email/_verify

ResendMyEmailVerification

rpc ResendMyEmailVerification(ResendMyEmailVerificationRequest) ResendMyEmailVerificationResponse

Sends a new email to the last given address to verify it

POST: /users/me/email/_resend_verification

GetMyPhone

rpc GetMyPhone(GetMyPhoneRequest) GetMyPhoneResponse

Returns the phone number of the authorized user

GET: /users/me/phone

SetMyPhone

rpc SetMyPhone(SetMyPhoneRequest) SetMyPhoneResponse

Sets the phone number of the authorized user An sms is sent to the number with a verification code

PUT: /users/me/phone

VerifyMyPhone

rpc VerifyMyPhone(VerifyMyPhoneRequest) VerifyMyPhoneResponse

Sets the phone number to verified

POST: /users/me/phone/_verify

ResendMyPhoneVerification

rpc ResendMyPhoneVerification(ResendMyPhoneVerificationRequest) ResendMyPhoneVerificationResponse

Resends a sms to the last given phone number, to verify it

POST: /users/me/phone/_resend_verification

RemoveMyPhone

rpc RemoveMyPhone(RemoveMyPhoneRequest) RemoveMyPhoneResponse

Removed the phone number of the authorized user

DELETE: /users/me/phone

RemoveMyAvatar

rpc RemoveMyAvatar(RemoveMyAvatarRequest) RemoveMyAvatarResponse

Remove my avatar

DELETE: /users/me/avatar

ListMyLinkedIDPs

rpc ListMyLinkedIDPs(ListMyLinkedIDPsRequest) ListMyLinkedIDPsResponse

Returns a list of all linked identity providers (social logins, eg. Google, Microsoft, AD, etc.)

POST: /users/me/idps/_search

RemoveMyLinkedIDP

rpc RemoveMyLinkedIDP(RemoveMyLinkedIDPRequest) RemoveMyLinkedIDPResponse

Removes a linked identity provider (social logins, eg. Google, Microsoft, AD, etc.)

DELETE: /users/me/idps/{idp_id}/{linked_user_id}

ListMyAuthFactors

rpc ListMyAuthFactors(ListMyAuthFactorsRequest) ListMyAuthFactorsResponse

Returns all configured authentication factors (second and multi)

POST: /users/me/auth_factors/_search

AddMyAuthFactorOTP

rpc AddMyAuthFactorOTP(AddMyAuthFactorOTPRequest) AddMyAuthFactorOTPResponse

Adds a new OTP (One Time Password) Second Factor to the authorized user Only one OTP can be configured per user

POST: /users/me/auth_factors/otp

VerifyMyAuthFactorOTP

rpc VerifyMyAuthFactorOTP(VerifyMyAuthFactorOTPRequest) VerifyMyAuthFactorOTPResponse

Verify the last added OTP (One Time Password)

POST: /users/me/auth_factors/otp/_verify

RemoveMyAuthFactorOTP

rpc RemoveMyAuthFactorOTP(RemoveMyAuthFactorOTPRequest) RemoveMyAuthFactorOTPResponse

Removed the configured OTP (One Time Password) Factor

DELETE: /users/me/auth_factors/otp

AddMyAuthFactorU2F

rpc AddMyAuthFactorU2F(AddMyAuthFactorU2FRequest) AddMyAuthFactorU2FResponse

Adds a new U2F (Universal Second Factor) to the authorized user Multiple U2Fs can be configured

POST: /users/me/auth_factors/u2f

VerifyMyAuthFactorU2F

rpc VerifyMyAuthFactorU2F(VerifyMyAuthFactorU2FRequest) VerifyMyAuthFactorU2FResponse

Verifies the last added U2F (Universal Second Factor) of the authorized user

POST: /users/me/auth_factors/u2f/_verify

RemoveMyAuthFactorU2F

rpc RemoveMyAuthFactorU2F(RemoveMyAuthFactorU2FRequest) RemoveMyAuthFactorU2FResponse

Removes the U2F Authentication from the authorized user

DELETE: /users/me/auth_factors/u2f/{token_id}

ListMyPasswordless

rpc ListMyPasswordless(ListMyPasswordlessRequest) ListMyPasswordlessResponse

Returns all configured passwordless authenticators of the authorized user

POST: /users/me/passwordless/_search

AddMyPasswordless

rpc AddMyPasswordless(AddMyPasswordlessRequest) AddMyPasswordlessResponse

Adds a new passwordless authenticator to the authorized user Multiple passwordless authentications can be configured

POST: /users/me/passwordless

rpc AddMyPasswordlessLink(AddMyPasswordlessLinkRequest) AddMyPasswordlessLinkResponse

Adds a new passwordless authenticator link to the authorized user and returns it directly This link enables the user to register a new device if current passwordless devices are all platform authenticators e.g. User has already registered Windows Hello and wants to register FaceID on the iPhone

POST: /users/me/passwordless/_link

rpc SendMyPasswordlessLink(SendMyPasswordlessLinkRequest) SendMyPasswordlessLinkResponse

Adds a new passwordless authenticator link to the authorized user and sends it to the registered email address This link enables the user to register a new device if current passwordless devices are all platform authenticators e.g. User has already registered Windows Hello and wants to register FaceID on the iPhone

POST: /users/me/passwordless/_send_link

VerifyMyPasswordless

rpc VerifyMyPasswordless(VerifyMyPasswordlessRequest) VerifyMyPasswordlessResponse

Verifies the last added passwordless configuration

POST: /users/me/passwordless/_verify

RemoveMyPasswordless

rpc RemoveMyPasswordless(RemoveMyPasswordlessRequest) RemoveMyPasswordlessResponse

Removes the passwordless configuration from the authorized user

DELETE: /users/me/passwordless/{token_id}

ListMyUserGrants

rpc ListMyUserGrants(ListMyUserGrantsRequest) ListMyUserGrantsResponse

Returns all user grants (authorizations) of the authorized user

POST: /usergrants/me/_search

ListMyProjectOrgs

rpc ListMyProjectOrgs(ListMyProjectOrgsRequest) ListMyProjectOrgsResponse

Returns a list of organisations where the authorized user has a user grant (authorization) in the context of the requested project

POST: /global/projectorgs/_search

ListMyZitadelFeatures

rpc ListMyZitadelFeatures(ListMyZitadelFeaturesRequest) ListMyZitadelFeaturesResponse

Returns a list of features, which are allowed on these organisation based on the subscription of the organisation

POST: /features/zitadel/me/_search

ListMyZitadelPermissions

rpc ListMyZitadelPermissions(ListMyZitadelPermissionsRequest) ListMyZitadelPermissionsResponse

Returns the permissions the authorized user has in ZITADEL based on his manager roles (e.g ORG_OWNER)

POST: /permissions/zitadel/me/_search

ListMyProjectPermissions

rpc ListMyProjectPermissions(ListMyProjectPermissionsRequest) ListMyProjectPermissionsResponse

Returns a list of roles for the authorized user and project

POST: /permissions/me/_search

ListMyMemberships

rpc ListMyMemberships(ListMyMembershipsRequest) ListMyMembershipsResponse

Show all the permissions my user has in ZITADEL (ZITADEL Manager) Limit should always be set, there is a default limit set by the service

POST: /memberships/me/_search

Messages

AddMyAuthFactorOTPRequest

This is an empty request

AddMyAuthFactorOTPResponse

FieldTypeDescriptionValidation
urlstring-
secretstring-
detailszitadel.v1.ObjectDetails-

AddMyAuthFactorU2FRequest

This is an empty request

AddMyAuthFactorU2FResponse

FieldTypeDescriptionValidation
keyzitadel.user.v1.WebAuthNKey-
detailszitadel.v1.ObjectDetails-

AddMyPasswordlessLinkRequest

This is an empty request

AddMyPasswordlessLinkResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-
linkstring-
expirationgoogle.protobuf.Duration-

AddMyPasswordlessRequest

This is an empty request

AddMyPasswordlessResponse

FieldTypeDescriptionValidation
keyzitadel.user.v1.WebAuthNKey-
detailszitadel.v1.ObjectDetails-

BulkRemoveMyMetadataRequest

FieldTypeDescriptionValidation
keysrepeated string-repeated.items.string.min_len: 1
repeated.items.string.max_len: 200

BulkRemoveMyMetadataResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

BulkSetMyMetadataRequest

FieldTypeDescriptionValidation
metadatarepeated BulkSetMyMetadataRequest.Metadata-

BulkSetMyMetadataRequest.Metadata

FieldTypeDescriptionValidation
keystring-string.min_len: 1
string.max_len: 200
valuebytes-bytes.min_len: 1
bytes.max_len: 500000

BulkSetMyMetadataResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

GetMyEmailRequest

This is an empty request

GetMyEmailResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-
emailzitadel.user.v1.Email-

GetMyMetadataRequest

FieldTypeDescriptionValidation
keystring-string.min_len: 1
string.max_len: 200

GetMyMetadataResponse

FieldTypeDescriptionValidation
metadatazitadel.metadata.v1.Metadata-

GetMyPasswordComplexityPolicyRequest

This is an empty request

GetMyPasswordComplexityPolicyResponse

FieldTypeDescriptionValidation
policyzitadel.policy.v1.PasswordComplexityPolicy-

GetMyPhoneRequest

This is an empty request

GetMyPhoneResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-
phonezitadel.user.v1.Phone-

GetMyProfileRequest

This is an empty request

GetMyProfileResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-
profilezitadel.user.v1.Profile-

GetMyUserRequest

This is an empty request the request parameters are read from the token-header

GetMyUserResponse

FieldTypeDescriptionValidation
userzitadel.user.v1.User-
last_logingoogle.protobuf.Timestamp-

GetSupportedLanguagesRequest

This is an empty request

GetSupportedLanguagesResponse

This is an empty response

FieldTypeDescriptionValidation
languagesrepeated string-

HealthzRequest

This is an empty request

HealthzResponse

This is an empty response

ListMyAuthFactorsRequest

This is an empty request

ListMyAuthFactorsResponse

FieldTypeDescriptionValidation
resultrepeated zitadel.user.v1.AuthFactor-

ListMyLinkedIDPsRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuerylist limitations and ordering

ListMyLinkedIDPsResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.idp.v1.IDPUserLink-

ListMyMembershipsRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuerythe field the result is sorted
queriesrepeated zitadel.user.v1.MembershipQuerycriterias the client is looking for

ListMyMembershipsResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.user.v1.Membership-

ListMyMetadataRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuery-
queriesrepeated zitadel.metadata.v1.MetadataQuery-

ListMyMetadataResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.metadata.v1.Metadata-

ListMyPasswordlessRequest

This is an empty request

ListMyPasswordlessResponse

FieldTypeDescriptionValidation
resultrepeated zitadel.user.v1.WebAuthNToken-

ListMyProjectOrgsRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuerylist limitations and ordering
queriesrepeated zitadel.org.v1.OrgQuerycriterias the client is looking for

ListMyProjectOrgsResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.org.v1.Org-

ListMyProjectPermissionsRequest

This is an empty request

ListMyProjectPermissionsResponse

FieldTypeDescriptionValidation
resultrepeated string-

ListMyRefreshTokensRequest

This is an empty request

ListMyRefreshTokensResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.user.v1.RefreshToken-

ListMyUserChangesRequest

FieldTypeDescriptionValidation
queryzitadel.change.v1.ChangeQuery-

ListMyUserChangesResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated zitadel.change.v1.Change-

ListMyUserGrantsRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuerylist limitations and ordering

ListMyUserGrantsResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
resultrepeated UserGrant-

ListMyUserSessionsRequest

This is an empty request

ListMyUserSessionsResponse

FieldTypeDescriptionValidation
resultrepeated zitadel.user.v1.Session-

ListMyZitadelFeaturesRequest

This is an empty request

ListMyZitadelFeaturesResponse

FieldTypeDescriptionValidation
resultrepeated string-

ListMyZitadelPermissionsRequest

This is an empty request

ListMyZitadelPermissionsResponse

FieldTypeDescriptionValidation
resultrepeated string-

RemoveMyAuthFactorOTPRequest

This is an empty request

RemoveMyAuthFactorOTPResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyAuthFactorU2FRequest

FieldTypeDescriptionValidation
token_idstring-string.min_len: 1
string.max_len: 200

RemoveMyAuthFactorU2FResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyAvatarRequest

This is an empty request

RemoveMyAvatarResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyLinkedIDPRequest

FieldTypeDescriptionValidation
idp_idstring-string.min_len: 1
string.max_len: 200
linked_user_idstring-string.min_len: 1
string.max_len: 200

RemoveMyLinkedIDPResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyMetadataRequest

FieldTypeDescriptionValidation
keystring-string.min_len: 1
string.max_len: 200

RemoveMyMetadataResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyPasswordlessRequest

FieldTypeDescriptionValidation
token_idstring-string.min_len: 1
string.max_len: 200

RemoveMyPasswordlessResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyPhoneRequest

This is an empty request

RemoveMyPhoneResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveMyUserRequest

This is an empty request the request parameters are read from the token-header

RemoveMyUserResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

ResendMyEmailVerificationRequest

This is an empty request

ResendMyEmailVerificationResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

ResendMyPhoneVerificationRequest

This is an empty request

ResendMyPhoneVerificationResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RevokeAllMyRefreshTokensRequest

This is an empty request

RevokeAllMyRefreshTokensResponse

This is an empty response

RevokeMyRefreshTokenRequest

FieldTypeDescriptionValidation
idstring-string.min_len: 1
string.max_len: 200

RevokeMyRefreshTokenResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

SendMyPasswordlessLinkRequest

This is an empty request

SendMyPasswordlessLinkResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

SetMyEmailRequest

FieldTypeDescriptionValidation
emailstringTODO: check if no value is allowedstring.email: true

SetMyEmailResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

SetMyMetadataRequest

FieldTypeDescriptionValidation
keystring-string.min_len: 1
string.max_len: 200
valuebytes-bytes.min_len: 1
bytes.max_len: 500000

SetMyMetadataResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

SetMyPhoneRequest

FieldTypeDescriptionValidation
phonestring-string.min_len: 1
string.max_len: 50
string.prefix: +

SetMyPhoneResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

UpdateMyPasswordRequest

FieldTypeDescriptionValidation
old_passwordstring-string.min_len: 1
string.max_bytes: 70
new_passwordstring-string.min_len: 1
string.max_bytes: 70

UpdateMyPasswordResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

UpdateMyProfileRequest

FieldTypeDescriptionValidation
first_namestring-string.min_len: 1
string.max_len: 200
last_namestring-string.min_len: 1
string.max_len: 200
nick_namestring-string.max_len: 200
display_namestring-string.min_len: 1
string.max_len: 200
preferred_languagestring-string.max_len: 10
genderzitadel.user.v1.Gender-

UpdateMyProfileResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

UpdateMyUserNameRequest

FieldTypeDescriptionValidation
user_namestring-string.min_len: 1
string.max_len: 200

UpdateMyUserNameResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

UserGrant

FieldTypeDescriptionValidation
org_idstring-
project_idstring-
user_idstring-
rolesrepeated string-
org_namestring-
grant_idstring-

VerifyMyAuthFactorOTPRequest

FieldTypeDescriptionValidation
codestring-string.min_len: 1
string.max_len: 200

VerifyMyAuthFactorOTPResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

VerifyMyAuthFactorU2FRequest

FieldTypeDescriptionValidation
verificationzitadel.user.v1.WebAuthNVerification-message.required: true

VerifyMyAuthFactorU2FResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

VerifyMyEmailRequest

FieldTypeDescriptionValidation
codestring-string.min_len: 1
string.max_len: 200

VerifyMyEmailResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

VerifyMyPasswordlessRequest

FieldTypeDescriptionValidation
verificationzitadel.user.v1.WebAuthNVerification-message.required: true

VerifyMyPasswordlessResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

VerifyMyPhoneRequest

FieldTypeDescriptionValidation
codestring-string.min_len: 1
string.max_len: 200

VerifyMyPhoneResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-