From 2797a0bb03e6aea32773b16a35975f0a2fadb36c Mon Sep 17 00:00:00 2001 From: Federico Coppede Date: Wed, 14 Jan 2026 12:15:28 -0300 Subject: [PATCH] docs: add clarification for user roles membership (#11359) This PR add some clarification to determine which roles are assigned to a user using either introspection or claims added to the token --- docs/docs/guides/integrate/retrieve-user-roles.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/docs/guides/integrate/retrieve-user-roles.md b/docs/docs/guides/integrate/retrieve-user-roles.md index ad5aba168..e0c1dd191 100644 --- a/docs/docs/guides/integrate/retrieve-user-roles.md +++ b/docs/docs/guides/integrate/retrieve-user-roles.md @@ -81,6 +81,14 @@ If you need them included in your ID Token, select **’User Roles Inside ID Tok Alternatively, you can include the claims `urn:iam:org:project:roles` or/and `urn:zitadel:iam:org:projects:roles` in your scope to achieve the same as above. +### Determine the roles assigned to a user + +To determine the roles assigned to a user, you have two options: + +- **Token claims**: Request that the relevant roles claim (such as `urn:zitadel:iam:org:project:{projectId}:roles`) is included in the token when you authenticate. The roles assigned to the user will then be part of the token’s payload. +- **Token introspection**: After a token is issued, you can introspect it using the [ZITADEL introspection endpoint](/docs/guides/integrate/token-introspection) to view the roles claim. This will return the roles assigned to the user according to the token. + + ### Retrieve roles from the userinfo endpoint The user info endpoint is **`${CUSTOM_DOMAIN}`/oidc/v1/userinfo**.