diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx
index 19ce0787ad..ea3c67567a 100644
--- a/deploy/authentication-setup.mdx
+++ b/deploy/authentication-setup.mdx
@@ -99,7 +99,7 @@ You host your documentation at `docs.foo.com` and your entire team has access to
### OAuth 2.0 prerequisites
* An OAuth or OIDC server that supports the Authorization Code Flow.
-* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable group-based access control).
+* For group-based access control, either an OAuth or OIDC server that returns groups in the `id_token` or `access_token`, or the ability to create an API endpoint accessible by OAuth access tokens.
### OAuth 2.0 setup
@@ -116,7 +116,8 @@ You host your documentation at `docs.foo.com` and your entire team has access to
* **Scopes** (optional): Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels.
* **Additional authorization parameters** (optional): Additional query parameters to add to the initial authorization request.
* **Token URL**: Your OAuth token exchange endpoint.
- * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Required for group-based access control. If omitted, the OAuth flow only verifies identity.
+ * **Token claims** (optional): Derive user groups directly from the JWT returned by your token endpoint, instead of hosting a separate user info endpoint. See [Derive groups from token claims](#derive-groups-from-token-claims).
+ * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Use this for group-based access control if your provider does not return groups in the `id_token` or `access_token`. If you omit both **Token claims** and **Info API URL**, the OAuth flow only verifies identity.
* **Logout URL** (optional): The native logout URL for your OAuth provider. When users log out, Mintlify validates the logout redirect against this configured URL for security. The redirect only succeeds if it exactly matches the configured `logoutUrl`. If you do not configure a logout URL, users redirect to `/login`. Mintlify redirects users with a `GET` request and does not append query parameters, so include any parameters (for example, `returnTo`) directly in the URL.
* **Redirect URL** (optional): The URL to redirect users to after authentication.
6. Click **Save changes**.
@@ -139,6 +140,51 @@ You host your documentation at `docs.foo.com` and your entire team has access to
+### Derive groups from token claims
+
+If your OAuth or OIDC provider already returns group membership in the `id_token` or `access_token`, you can skip hosting a user info endpoint and let Mintlify read groups directly from the token that your token endpoint returns.
+
+When you configure **Token claims**, Mintlify:
+
+* Decodes the configured token from the token endpoint response.
+* Extracts the configured claim and normalizes it into a list of groups.
+* Uses those groups to enforce [group-based access control](#control-access-with-groups).
+* Skips any request to your **Info API URL** for group data.
+
+Configure these fields under **Token claims**:
+
+* **Source**: The token to read groups from. Choose `id_token` (the default) or `access_token`. If you use `id_token`, include `openid` in your OAuth **Scopes**.
+* **Groups claim**: The claim to read groups from. You can use a top-level claim name, a namespaced URI claim, or a dotted path into nested claims. For example:
+ * `groups` for a top-level array claim.
+ * `https://your-domain.example.com/groups` for an Auth0 namespaced claim.
+ * `realm_access.roles` for a Keycloak realm role claim.
+
+Mintlify accepts the claim value as either a JSON array of strings or a single string.
+
+
+ Group derivation from token claims is fail-closed. If the configured token is missing from the token response (for example, requesting `id_token` without the `openid` scope), Mintlify blocks the sign-in instead of logging the user in with no groups.
+
+
+#### Token claims example
+
+For a provider that returns an `access_token` containing a `groups` claim:
+
+```json
+{
+ "source": "access_token",
+ "groupsClaim": "groups"
+}
+```
+
+For a Keycloak provider that returns roles in a nested claim:
+
+```json
+{
+ "source": "id_token",
+ "groupsClaim": "realm_access.roles"
+}
+```
+
### OAuth 2.0 example
You host your documentation at `docs.foo.com` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.
diff --git a/es/deploy/authentication-setup.mdx b/es/deploy/authentication-setup.mdx
index 3f5030a586..5d374294b1 100644
--- a/es/deploy/authentication-setup.mdx
+++ b/es/deploy/authentication-setup.mdx
@@ -107,7 +107,7 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
### Requisitos previos de OAuth 2.0
* Un servidor OAuth u OIDC que admita el flujo de código de autorización (Authorization Code Flow).
- * Capacidad para crear un endpoint de API accesible mediante tokens de acceso OAuth (opcional, para habilitar el control de acceso basado en grupos).
+ * Para el control de acceso basado en grupos, un servidor OAuth u OIDC que devuelva los grupos en el `id_token` o el `access_token`, o la capacidad para crear un endpoint de API accesible mediante tokens de acceso OAuth.
### Configuración de OAuth 2.0
@@ -125,7 +125,8 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
* **Scopes** (opcional): Permisos que se van a solicitar. Copia la cadena de scope **completa** (por ejemplo, para un scope como `provider.users.docs`, copia el `provider.users.docs` completo). Usa varios scopes si necesitas diferentes niveles de acceso.
* **Additional authorization parameters** (opcional): Parámetros de consulta adicionales que se agregarán a la solicitud de autorización inicial.
* **Token URL**: Tu endpoint de intercambio de tokens de OAuth.
- * **Info API URL** (opcional): Endpoint en tu servidor al que Mintlify llama para obtener información del usuario. Obligatorio para el control de acceso basado en grupos. Si se omite, el flujo de OAuth solo verifica la identidad.
+ * **Token claims** (opcional): Deriva los grupos de usuario directamente del JWT que devuelve tu endpoint de tokens, en lugar de alojar un endpoint independiente de información de usuario. Consulta [Derivar grupos a partir de claims del token](#derive-groups-from-token-claims).
+ * **Info API URL** (opcional): Endpoint en tu servidor al que Mintlify llama para obtener la información del usuario. Usa esta opción para el control de acceso basado en grupos si tu proveedor no devuelve los grupos en el `id_token` o el `access_token`. Si se omiten tanto **Token claims** como **Info API URL**, el flujo de OAuth solo verifica la identidad.
* **Logout URL** (opcional): La URL de cierre de sesión nativa de tu proveedor de OAuth. Cuando los usuarios cierran sesión, Mintlify valida la redirección de cierre de sesión frente a esta URL configurada por motivos de seguridad. La redirección solo se completa si coincide exactamente con el `logoutUrl` configurado. Si no configuras una Logout URL, los usuarios se redirigen a `/login`. Mintlify redirige a los usuarios con una solicitud `GET` y no agrega parámetros de consulta, por lo que debes incluir cualquier parámetro (por ejemplo, `returnTo`) directamente en la URL.
* **Redirect URL** (opcional): La URL a la que se redirigirá a los usuarios después de la autenticación.
@@ -152,6 +153,51 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
+ ### Derivar grupos a partir de claims del token
+
+ Si tu proveedor de OAuth u OIDC ya devuelve la pertenencia a grupos en el `id_token` o el `access_token`, puedes evitar alojar un endpoint de información de usuario y dejar que Mintlify lea los grupos directamente del token que devuelve tu endpoint de tokens.
+
+ Cuando configuras **Token claims**, Mintlify:
+
+ * Decodifica el token configurado a partir de la respuesta del endpoint de tokens.
+ * Extrae el claim configurado y lo normaliza en una lista de grupos.
+ * Usa esos grupos para aplicar el [control de acceso basado en grupos](#control-access-with-groups).
+ * Omite cualquier solicitud a tu **Info API URL** para obtener datos de grupos.
+
+ Configura estos campos en **Token claims**:
+
+ * **Source**: El token del que se leerán los grupos. Elige `id_token` (el valor predeterminado) o `access_token`. Si usas `id_token`, incluye `openid` en los **Scopes** de OAuth.
+ * **Groups claim**: El claim del que se leerán los grupos. Puedes usar el nombre de un claim de nivel superior, un claim con URI con espacio de nombres o una ruta con puntos hacia claims anidados. Por ejemplo:
+ * `groups` para un claim de arreglo de nivel superior.
+ * `https://your-domain.example.com/groups` para un claim con espacio de nombres de Auth0.
+ * `realm_access.roles` para un claim de rol de realm de Keycloak.
+
+ Mintlify acepta el valor del claim como un arreglo JSON de cadenas o como una única cadena.
+
+
+ La derivación de grupos a partir de claims del token es fail-closed. Si el token configurado no está presente en la respuesta del token (por ejemplo, si se solicita `id_token` sin el scope `openid`), Mintlify bloquea el inicio de sesión en lugar de iniciar sesión al usuario sin grupos.
+
+
+ #### Ejemplo de Token claims
+
+ Para un proveedor que devuelve un `access_token` que contiene un claim `groups`:
+
+ ```json
+ {
+ "source": "access_token",
+ "groupsClaim": "groups"
+ }
+ ```
+
+ Para un proveedor Keycloak que devuelve roles en un claim anidado:
+
+ ```json
+ {
+ "source": "id_token",
+ "groupsClaim": "realm_access.roles"
+ }
+ ```
+
### Ejemplo de OAuth 2.0
Alojas tu documentación en `docs.foo.com` y tienes un servidor OAuth existente en `auth.foo.com` que admite el flujo de código de autorización (Authorization Code Flow).
diff --git a/fr/deploy/authentication-setup.mdx b/fr/deploy/authentication-setup.mdx
index 9ed71495e2..36f152edb3 100644
--- a/fr/deploy/authentication-setup.mdx
+++ b/fr/deploy/authentication-setup.mdx
@@ -107,7 +107,7 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
### Prérequis OAuth 2.0
* Un serveur OAuth ou OIDC qui prend en charge le flux Authorization Code (Authorization Code Flow).
- * Capacité à créer un endpoint d'API accessible via des jetons d'accès OAuth (facultatif, pour activer le contrôle d'accès basé sur les groupes).
+ * Pour le contrôle d'accès basé sur les groupes, soit un serveur OAuth ou OIDC qui renvoie les groupes dans l'`id_token` ou l'`access_token`, soit la capacité à créer un endpoint d'API accessible via des jetons d'accès OAuth.
### Configuration OAuth 2.0
@@ -125,7 +125,8 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
* **Scopes** (facultatif) : Autorisations à demander. Copiez la chaîne de scope **entière** (par exemple, pour un scope comme `provider.users.docs`, copiez l’intégralité de `provider.users.docs`). Utilisez plusieurs scopes si vous avez besoin de niveaux d’accès différents.
* **Additional authorization parameters** (facultatif) : Paramètres de requête supplémentaires à ajouter à la requête d’autorisation initiale.
* **Token URL** : Votre endpoint d’échange de jeton OAuth.
- * **Info API URL** (facultatif) : Endpoint sur votre serveur que Mintlify appelle pour récupérer les informations utilisateur. Requis pour le contrôle d’accès basé sur les groupes. S’il est omis, le flux OAuth vérifie uniquement l’identité.
+ * **Token claims** (facultatif) : Dérivez les groupes d’utilisateurs directement depuis le JWT renvoyé par votre endpoint de jeton, au lieu d’héberger un endpoint d’informations utilisateur distinct. Voir [Dériver les groupes à partir des revendications du jeton](#derive-groups-from-token-claims).
+ * **Info API URL** (facultatif) : Endpoint sur votre serveur que Mintlify appelle pour récupérer les informations utilisateur. Utilisez ce champ pour le contrôle d’accès basé sur les groupes si votre fournisseur ne renvoie pas les groupes dans l’`id_token` ou l’`access_token`. Si **Token claims** et **Info API URL** sont tous deux omis, le flux OAuth vérifie uniquement l’identité.
* **Logout URL** (facultatif) : L’URL de déconnexion native de votre fournisseur OAuth. Lorsque les utilisateurs se déconnectent, Mintlify valide la redirection de déconnexion par rapport à l’URL configurée, pour des raisons de sécurité. La redirection ne réussit que si elle correspond exactement à la valeur de `logoutUrl` configurée. Si vous ne configurez pas d’URL de déconnexion, les utilisateurs sont redirigés vers `/login`. Mintlify redirige les utilisateurs avec une requête `GET` et n’ajoute aucun paramètre de requête. Incluez donc directement tous les paramètres (par exemple, `returnTo`) dans l’URL.
* **Redirect URL** (facultatif) : L’URL vers laquelle rediriger les utilisateurs après l’authentification.
@@ -152,6 +153,51 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
+ ### Dériver les groupes à partir des revendications du jeton
+
+ Si votre fournisseur OAuth ou OIDC renvoie déjà l’appartenance aux groupes dans l’`id_token` ou l’`access_token`, vous pouvez éviter d’héberger un endpoint d’informations utilisateur et laisser Mintlify lire les groupes directement depuis le jeton renvoyé par votre endpoint de jeton.
+
+ Lorsque vous configurez **Token claims**, Mintlify :
+
+ * Décode le jeton configuré à partir de la réponse de l’endpoint de jeton.
+ * Extrait la revendication configurée et la normalise en une liste de groupes.
+ * Utilise ces groupes pour appliquer le [contrôle d’accès basé sur les groupes](#control-access-with-groups).
+ * Ignore toute requête vers votre **Info API URL** pour les données de groupes.
+
+ Configurez ces champs sous **Token claims** :
+
+ * **Source** : Le jeton dans lequel lire les groupes. Choisissez `id_token` (valeur par défaut) ou `access_token`. Si vous utilisez `id_token`, incluez `openid` dans vos **Scopes** OAuth.
+ * **Groups claim** : La revendication depuis laquelle lire les groupes. Vous pouvez utiliser un nom de revendication de premier niveau, une revendication d’URI avec espace de noms, ou un chemin en notation pointée vers des revendications imbriquées. Par exemple :
+ * `groups` pour une revendication de tableau de premier niveau.
+ * `https://your-domain.example.com/groups` pour une revendication Auth0 avec espace de noms.
+ * `realm_access.roles` pour une revendication de rôle de realm Keycloak.
+
+ Mintlify accepte la valeur de la revendication sous la forme d’un tableau JSON de chaînes ou d’une chaîne unique.
+
+
+ La dérivation des groupes à partir des revendications du jeton fonctionne en mode « fail-closed ». Si le jeton configuré est absent de la réponse de jeton (par exemple, en demandant `id_token` sans le scope `openid`), Mintlify bloque la connexion au lieu de connecter l’utilisateur sans aucun groupe.
+
+
+ #### Exemple de Token claims
+
+ Pour un fournisseur qui renvoie un `access_token` contenant une revendication `groups` :
+
+ ```json
+ {
+ "source": "access_token",
+ "groupsClaim": "groups"
+ }
+ ```
+
+ Pour un fournisseur Keycloak qui renvoie les rôles dans une revendication imbriquée :
+
+ ```json
+ {
+ "source": "id_token",
+ "groupsClaim": "realm_access.roles"
+ }
+ ```
+
### Exemple OAuth 2.0
Vous hébergez votre documentation sur `docs.foo.com` et vous disposez d’un serveur OAuth existant sur `auth.foo.com` qui prend en charge le flux « Authorization Code ».
diff --git a/zh/deploy/authentication-setup.mdx b/zh/deploy/authentication-setup.mdx
index 626bc59140..842f2c3257 100644
--- a/zh/deploy/authentication-setup.mdx
+++ b/zh/deploy/authentication-setup.mdx
@@ -107,7 +107,7 @@ keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password', 'private']
### OAuth 2.0 前提条件
* 支持 Authorization Code Flow (授权码流程) 的 OAuth 或 OIDC 服务器。
- * 能够创建可通过 OAuth 访问令牌访问的 API 端点 (可选，用于启用基于用户组的访问控制) 。
+ * 对于基于用户组的访问控制，需要一个能在 `id_token` 或 `access_token` 中返回 groups 的 OAuth 或 OIDC 服务器，或者能够创建可通过 OAuth 访问令牌访问的 API 端点。
### OAuth 2.0 设置
@@ -125,7 +125,8 @@ keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password', 'private']
* **Scopes** (可选) ：要请求的权限。复制 **完整的** scope 字符串 (例如，对于 `provider.users.docs` 这样的 scope，复制完整的 `provider.users.docs`) 。如果需要不同的访问级别，可以使用多个 scope。
* **Additional authorization parameters** (可选) ：要添加到初始授权请求中的其他 query 参数。
* **Token URL**：你的 OAuth 令牌交换端点。
- * **Info API URL** (可选) ：你服务器上的一个端点，Mintlify 会调用它来获取用户信息。对于基于用户组的访问控制是必填项。如果省略，OAuth 流程只会验证身份。
+ * **Token claims** (可选) ：直接从你的 token 端点返回的 JWT 中派生用户组，而无需再单独托管一个用户信息端点。参见[从 token claims 派生 groups](#derive-groups-from-token-claims)。
+ * **Info API URL** (可选) ：你服务器上的一个端点，Mintlify 会调用它来获取用户信息。如果你的提供方不在 `id_token` 或 `access_token` 中返回 groups，可将此端点用于基于用户组的访问控制。如果同时省略 **Token claims** 和 **Info API URL**，OAuth 流程只会验证身份。
* **Logout URL** (可选) ：你的 OAuth 提供方自带的登出 URL。用户登出时，Mintlify 会将登出重定向与该配置的 URL 进行校验，以确保安全性。只有当重定向地址与配置的 `logoutUrl` 完全匹配时，重定向才会成功。如果你未配置登出 URL，用户会被重定向到 `/login`。Mintlify 会使用 `GET` 请求重定向用户，并且不会追加任何 query 参数，因此请将所有参数 (例如 `returnTo`) 直接包含在 URL 中。
* **Redirect URL** (可选) ：在认证完成后重定向用户的 URL。
@@ -152,6 +153,51 @@ keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password', 'private']
+ ### 从 token claims 派生 groups
+
+ 如果你的 OAuth 或 OIDC 提供方已经在 `id_token` 或 `access_token` 中返回用户组信息，你可以省去托管用户信息端点的步骤，让 Mintlify 直接从你的 token 端点返回的 token 中读取 groups。
+
+ 当你配置 **Token claims** 时，Mintlify 会：
+
+ * 从 token 端点响应中解码所配置的 token。
+ * 提取所配置的 claim，并将其规范化为一个 groups 列表。
+ * 使用这些 groups 来执行[基于用户组的访问控制](#control-access-with-groups)。
+ * 跳过对 **Info API URL** 的任何 groups 数据请求。
+
+ 在 **Token claims** 下配置以下字段：
+
+ * **Source**：读取 groups 的目标 token。选择 `id_token` (默认) 或 `access_token`。如果使用 `id_token`，请在你的 OAuth **Scopes** 中包含 `openid`。
+ * **Groups claim**：用于读取 groups 的 claim。你可以使用顶层 claim 名称、带命名空间的 URI claim，或指向嵌套 claim 的点号路径。例如：
+ * `groups` 表示顶层数组 claim。
+ * `https://your-domain.example.com/groups` 表示 Auth0 命名空间 claim。
+ * `realm_access.roles` 表示 Keycloak realm role claim。
+
+ Mintlify 接受的 claim 值可以是字符串的 JSON 数组，也可以是单个字符串。
+
+
+ 从 token claims 派生 groups 采用 fail-closed 策略。如果在 token 响应中缺少所配置的 token (例如，在未包含 `openid` scope 的情况下请求 `id_token`) ，Mintlify 会阻止登录，而不是让用户以无任何 groups 的状态登录。
+
+
+ #### Token claims 示例
+
+ 对于返回包含 `groups` claim 的 `access_token` 的提供方：
+
+ ```json
+ {
+ "source": "access_token",
+ "groupsClaim": "groups"
+ }
+ ```
+
+ 对于在嵌套 claim 中返回 roles 的 Keycloak 提供方：
+
+ ```json
+ {
+ "source": "id_token",
+ "groupsClaim": "realm_access.roles"
+ }
+ ```
+
### OAuth 2.0 示例
你将文档托管在 `docs.foo.com`，并且你有一个现有的 OAuth 服务器 `auth.foo.com`，它支持 Authorization Code Flow。