Skip to main content

Scopes in ZITADEL

ZITADEL supports the usage of scopes as way of requesting information from the IAM and also instruct ZITADEL to do certain operations.

Standard Scopes

ScopesDescription
openidWhen using openid connect this is a mandatory scope
profileOptional scope to request the profile of the subject
emailOptional scope to request the email of the subject
addressOptional scope to request the address of the subject
phoneOptional scope to request the phone of the subject
offline_accessOptional scope to request a refresh_token (only possible when using code flow)

Custom Scopes

This feature is not yet released

Reserved Scopes

In addition to the standard compliant scopes we utilize the following scopes.

ScopesExampleDescription
urn:zitadel:iam:org:project:role:{rolekey}urn:zitadel:iam:org:project:role:userBy using this scope a client can request the claim urn:zitadel:iam:org:project:roles to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the project a client belongs to.
urn:zitadel:iam:org:projects:rolesurn:zitadel:iam:org:projects:rolesBy using this scope a client can request the claim urn:zitadel:iam:org:project:{projectid}:roles to be asserted for each requested project. All projects of the token audience, requested by the urn:zitadel:iam:org:project:id:{projectid}:aud scopes will be used.
urn:zitadel:iam:org:id:{id}urn:zitadel:iam:org:id:178204173316174381When requesting this scope ZITADEL will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed. It will assert the urn:zitadel:iam:user:resourceowner claims.
urn:zitadel:iam:org:domain:primary:{domainname}urn:zitadel:iam:org:domain:primary:acme.chWhen requesting this scope ZITADEL will enforce that the user is a member of the selected organization and the username is suffixed by the provided domain. If the organization does not exist a failure is displayed
urn:zitadel:iam:role:{rolename}
urn:zitadel:iam:org:roles:id:{orgID}urn:zitadel:iam:org:roles:id:178204173316174381This scope can be used one or more times to limit the granted organization IDs in the returned roles. Unknown organization IDs are ignored. When this scope is not used, all granted organizations are returned inside the roles.1
urn:zitadel:iam:org:project:id:{projectid}:audurn:zitadel:iam:org:project:id:69234237810729019:audBy adding this scope, the requested projectid will be added to the audience of the access token
urn:zitadel:iam:org:project:id:zitadel:audurn:zitadel:iam:org:project:id:zitadel:audBy adding this scope, the ZITADEL project ID will be added to the audience of the access token
urn:zitadel:iam:user:metadataurn:zitadel:iam:user:metadataBy adding this scope, the metadata of the user will be included in the token. The values are base64 encoded.
urn:zitadel:iam:user:resourceownerurn:zitadel:iam:user:resourceownerBy adding this scope, the resourceowner (id, name, primary_domain) of the user will be included in the token.
urn:zitadel:iam:org:idp:id:{idp_id}urn:zitadel:iam:org:idp:id:76625965177954913By adding this scope the user will directly be redirected to the identity provider to authenticate. Make sure you also send the primary domain scope if a custom login policy is configured. Otherwise the system will not be able to identify the identity provider.

Footnotes

  1. urn:zitadel:iam:org:roles:id:{orgID} is not supported when the oidcLegacyIntrospection feature flag is enabled.