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

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

GetMyLabelPolicy​

rpc GetMyLabelPolicy(GetMyLabelPolicyRequest) GetMyLabelPolicyResponse

Returns the label policy of the current organisation

GET: /policies/label

GetMyPrivacyPolicy​

rpc GetMyPrivacyPolicy(GetMyPrivacyPolicyRequest) GetMyPrivacyPolicyResponse

Returns the privacy policy of the current organisation

GET: /policies/privacy

GetMyLoginPolicy​

rpc GetMyLoginPolicy(GetMyLoginPolicyRequest) GetMyLoginPolicyResponse

Returns the login policy of the current organisation

GET: /policies/login

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-

GetMyLabelPolicyRequest​

This is an empty request

GetMyLabelPolicyResponse​

FieldTypeDescriptionValidation
policyzitadel.policy.v1.LabelPolicy-

GetMyLoginPolicyRequest​

This is an empty request

GetMyLoginPolicyResponse​

FieldTypeDescriptionValidation
policyzitadel.policy.v1.LoginPolicy-

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-

GetMyPrivacyPolicyRequest​

This is an empty request

GetMyPrivacyPolicyResponse​

FieldTypeDescriptionValidation
policyzitadel.policy.v1.PrivacyPolicy-

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
resultrepeated zitadel.change.v1.Changezitadel.v1.ListDetails details = 1; was always returned empty (as we cannot get the necessary infos)

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-

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
emailstring-string.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-