Skip to main content

Claims in ZITADEL

ZITADEL asserts claims on different places according to the corresponding specifications or project and clients settings. Please check below the matrix for an overview where which scope is asserted.

ClaimsUserinfoIntrospectionID TokenAccess Token
acrNoNoYesNo
actNoAfter Token Exchange with actor_tokenAfter Token Exchange with actor_tokenWhen JWT and after Token Exchange with actor_token
addressWhen requestedWhen requestedWhen requested and response_type id_tokenNo
amrNoNoYesNo
audNoYesYesWhen JWT
auth_timeNoNoYesNo
azp (client_id when Introspect)NoYesYesWhen JWT
emailWhen requestedWhen requestedWhen requested and response_type id_tokenNo
email_verifiedWhen requestedWhen requestedWhen requested and response_type id_tokenNo
expNoYesYesWhen JWT
family_nameWhen requestedWhen requestedWhen requested and response_type id_tokenNo
genderWhen requestedWhen requestedWhen requested and response_type id_tokenNo
given_nameWhen requestedWhen requestedWhen requested and response_type id_tokenNo
iatNoYesYesWhen JWT
issNoYesYesWhen JWT
jtiNoYesNoWhen JWT
localeWhen requestedWhen requestedWhen requested and response_type id_tokenNo
nameWhen requestedWhen requestedWhen requested and response_type id_tokenNo
nbfNoYesYesWhen JWT
nonceNoNoYesNo
phoneWhen requestedWhen requestedWhen requested and response_type id_tokenNo
phone_verifiedWhen requestedWhen requestedWhen requested and response_type id_tokenNo
preferred_username (username when Introspect)When requestedWhen requestedYesNo
subYesYesYesWhen JWT
urn:zitadel:iam:org:domain:primary:{domainname}When requestedWhen requestedWhen requestedWhen JWT and requested
urn:zitadel:iam:org:project:rolesWhen requestedWhen requestedWhen requested or configuredWhen JWT and requested or configured
urn:zitadel:iam:user:metadataWhen requestedWhen requestedWhen requestedWhen JWT and requested
urn:zitadel:iam:user:resourceowner:idWhen requestedWhen requestedWhen requestedWhen JWT and requested
urn:zitadel:iam:user:resourceowner:nameWhen requestedWhen requestedWhen requestedWhen JWT and requested
urn:zitadel:iam:user:resourceowner:primary_domainWhen requestedWhen requestedWhen requestedWhen JWT and requested

Standard Claims​

ClaimsExampleDescription
acrTBATBA
act{"iss": "$CUSTOM-DOMAIN","sub": "259241944654282754"}JSON object describing the actor from the actor_token after token exchange
addressLerchenfeldstrasse 3, 9014 St. GallenTBA
amrpwd mfaAuthentication Method References as defined in RFC8176
password value is deprecated, please check pwd
aud69234237810729019The audience of the token, by default all client id's and the project id are included
auth_time1311280969Unix time of the authentication
azp69234237810729234Client id of the client who requested the token
emailroad.runner@acme.chEmail Address of the subject
email_verifiedtrueBoolean if the email was verified by ZITADEL
exp1311281970Time the token expires (as unix time)
family_nameRunnerThe subjects family name
genderotherGender of the subject
given_nameRoadGiven name of the subject
iat1311280970Time of the token was issued at (as unix time)
iss$CUSTOM-DOMAINIssuing domain of a token
jti69234237813329048Unique id of the token
localeenLanguage from the subject
nameRoad RunnerThe subjects full name
nbf1311280970Time the token must not be used before (as unix time)
nonceblQtVEJHNTF0WHhFQmhqZ0RqeHJsdzdkd2d...The nonce provided by the client
phone+41 79 XXX XX XXPhone number provided by the user
phone_verifiedtrueBoolean if the phone was verified by ZITADEL
preferred_usernameroad.runner@acme.caos.chZITADEL's login name of the user. Consist of username@primarydomain
sub77776025198584418Subject ID of the user

Custom Claims​

Custom claims are being inserted into user tokens in addition to the standard claims. Your app can use custom claims to handle more complex scenarios, such as restricting access based on these claims.

You can add custom claims using the complement token flow of the actions feature.

Multiple examples of Actions that result in custom claims can be found in our Marketplace for ZITADEL Actions.

Static values as custom claim​

examples/add_claim.js
loading...

Metadata as custom claim​

examples/add_metadata.js
loading...

Format roles claims​

examples/custom_roles.js
loading...

Reserved Claims​

ZITADEL reserves some claims to assert certain data. Please check out the reserved scopes.

ClaimsExampleDescription
urn:zitadel:iam:action:{actionname}:log{"urn:zitadel:iam:action:appendCustomClaims:log": ["test log", "another test log"]}This claim is set during Actions as a log, e.g. if two custom claims with the same keys are set.
urn:zitadel:iam:org:domain:primary:{domainname}{"urn:zitadel:iam:org:domain:primary": "acme.ch"}This claim represents the primary domain of the organization the user belongs to.
urn:zitadel:iam:org:project:roles{"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }When roles are asserted, ZITADEL does this by providing the id and primaryDomain below the role. This gives you the option to check in which organization a user has the role on the current project (where your client belongs to).
urn:zitadel:iam:org:project:{projectid}:roles{"urn:zitadel:iam:org:project:id3:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }When roles are asserted, ZITADEL does this by providing the id and primaryDomain below the role. This gives you the option to check in which organization a user has the role on a specific project.
urn:zitadel:iam:roles:{rolename}TBATBA
urn:zitadel:iam:user:metadata{"urn:zitadel:iam:user:metadata": [ {"key": "VmFsdWU=" } ] }The metadata claim will include all metadata of a user. The values are base64 encoded.
urn:zitadel:iam:user:resourceowner:id{"urn:zitadel:iam:user:resourceowner:id": "orgid"}This claim represents the id of the resource owner organisation of the user.
urn:zitadel:iam:user:resourceowner:name{"urn:zitadel:iam:user:resourceowner:name": "ACME"}This claim represents the name of the resource owner organisation of the user.
urn:zitadel:iam:user:resourceowner:primary_domain{"urn:zitadel:iam:user:resourceowner:primary_domain": "acme.ch"}This claim represents the primary domain of the resource owner organisation of the user.