> ## Documentation Index > Fetch the complete documentation index at: https://mintlify-mintlify-add-i-to-quickstart-8818.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Configuración de Personalización > Permite que los usuarios inicien sesión para obtener experiencias de documentación personalizadas La Personalización adapta tu documentación a cada usuario cuando ha iniciado sesión. Por ejemplo, puedes completar previamente sus claves de API, mostrar contenido específico según su plan o rol, u ocultar secciones a las que no necesitan acceder.
## Funciones de personalización
Personaliza el contenido con estas capacidades de personalización.
### Autorrelleno de clave de API
Completa automáticamente los campos del Área de pruebas de API con valores específicos del usuario devolviendo nombres de campo que coincidan en tus datos de usuario. Los nombres de los campos en tus datos de usuario deben coincidir exactamente con los nombres del Área de pruebas de API para que el autorrelleno funcione.
### Contenido MDX dinámico
Muestra contenido dinámico según información del usuario como el nombre, el plan u organización usando la variable `user`. ```jsx ¡Bienvenido/a de nuevo, {user.firstName}! Tu plan {user.org?.plan} incluye... ``` Consulta la sección [Formato de datos de usuario](#user-data-format) más abajo para ver ejemplos detallados y orientación de implementación.
### Visibilidad de la página
Restringe qué páginas son visibles para tus usuarios añadiendo campos `groups` al frontmatter de tus páginas. De forma predeterminada, cada página es visible para todos los usuarios. Los usuarios solo verán las páginas de los `groups` a los que pertenezcan. ```mdx --- title: "Gestión de tus usuarios" description: "Añadir y eliminar usuarios de tu organización" groups: ["admin"] --- ```
## Formato de datos del usuario
Al implementar la personalización, tu sistema devuelve los datos del usuario en un formato específico que permite personalizar el contenido. Estos datos pueden enviarse como un objeto JSON sin procesar o dentro de un JWT firmado, según tu método de intercambio. La estructura de los datos es la misma en ambos casos. ```tsx type User = { expiresAt?: number; groups?: string[]; content?: Record; apiPlaygroundInputs?: { header?: Record; query?: Record; cookie?: Record; server?: Record; }; }; ``` Tiempo de expiración de la sesión en **segundos desde el epoch**. Si el usuario carga una página después de este tiempo, sus datos almacenados se eliminan automáticamente y debe volver a autenticarse. Para intercambios con JWT: Esto difiere del claim `exp` del JWT, que determina cuándo un JWT se considera inválido. Por seguridad, establece el claim `exp` del JWT en una duración corta (10 segundos o menos). Usa `expiresAt` para la duración real de la sesión (de horas a semanas). Lista de grupos a los que pertenece el usuario. Las páginas con `groups` coincidentes en su frontmatter son visibles para este usuario. **Ejemplo**: Un usuario con `groups: ["admin", "engineering"]` puede acceder a páginas etiquetadas con los grupos `admin` o `engineering`. Datos personalizados accesibles en tu contenido `MDX` mediante la variable `user`. Úsalo para la personalización dinámica en toda tu documentación. **Ejemplo básico**: ```json { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } ``` **Uso en `MDX`**: ```mdx Welcome back, {user.firstName}! Your {user.plan} plan includes... ``` Con los datos de `user` del ejemplo, se renderizaría como: Welcome back, Ronan! Your Enterprise plan includes... **Renderizado condicional avanzado**: ```jsx Authentication is an enterprise feature. { user.org === undefined ? <>To access this feature, first create an account at the Mintlify dashboard. : user.org.plan !== 'enterprise' ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See our pricing page for information about upgrading. : <>To request this feature for your enterprise org, contact your admin. } ``` La información en `user` solo está disponible para usuarios autenticados. Para los usuarios que no han iniciado sesión, el valor de `user` será `{}`. Para evitar que la página falle con usuarios no autenticados, usa siempre encadenamiento opcional en los campos de `user`. Por ejemplo, `{user.org?.plan}`. Valores específicos del usuario que precargan los campos del Área de pruebas de API. Ahorra tiempo a los usuarios al autocompletar sus datos cuando prueban APIs. **Ejemplo**: ```json { "header": { "X-API-Key": "user_api_key_123" }, "server": { "subdomain": "foo" }, "query": { "org_id": "12345" } } ``` Si un usuario hace solicitudes en un subdominio específico, puedes enviar `{ server: { subdomain: 'foo' } }` como un campo `apiPlaygroundInputs`. Este valor se precargará en cualquier página de API con el valor `subdomain`. Los campos `header`, `query` y `cookie` solo se precargarán si forman parte de tu [esquema de seguridad de OpenAPI](https://swagger.io/docs/specification/authentication/). Si un campo está en las secciones `Authorization` o `Server`, se precargará. Crear un parámetro de encabezado estándar llamado `Authorization` no habilitará esta función.
### Datos de usuario de ejemplo
```json { "expiresAt": 1735689600, "groups": ["admin", "beta-users"], "content": { "firstName": "Jane", "lastName": "Smith", "company": "TechCorp", "plan": "Enterprise", "region": "us-west" }, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer abc123", "X-Org-ID": "techcorp" }, "server": { "environment": "production", "region": "us-west" } } } ```
## Configuración de la personalización
Selecciona el método de handshake que deseas configurar. ### Requisitos previos * Un sistema de autenticación que pueda generar y firmar JWT * Un servicio de backend que pueda crear URL de redirección ### Implementación 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Selecciona **Personalization**. 3. Selecciona **JWT**. 4. Introduce la URL de tu flujo de inicio de sesión existente y selecciona **Save changes**. 5. Selecciona **Generate new key**. 6. Almacena tu clave de forma segura en un lugar al que tu backend pueda acceder. Modifica tu flujo de inicio de sesión existente para incluir estos pasos después de que el usuario inicie sesión: * Crea un JWT que contenga la información del usuario autenticado en el formato `User`. Consulta la sección [User data format](#user-data-format) más arriba para obtener más información. * Firma el JWT con la clave secreta usando el algoritmo ES256. * Crea una URL de redirección de regreso a tu documentación, incluyendo el JWT como hash. ### Ejemplo Tu documentación está alojada en `docs.foo.com`. Quieres que tu documentación esté separada de tu panel (o no tienes un panel) y habilitar la personalización. Genera un secreto de JWT. Luego crea un endpoint de inicio de sesión en `https://foo.com/docs-login` que inicie un flujo de inicio de sesión hacia tu documentación. Después de verificar las credenciales del usuario: * Genera un JWT con los datos del usuario en el formato de Mintlify. * Firma el JWT y redirige a `https://docs.foo.com#{SIGNED_JWT}`. ```ts import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), groups: res.locals.user.groups, content: { firstName: res.locals.user.firstName, lastName: res.locals.user.lastName, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'ES256' }) .setExpirationTime('10 s') .sign(signingKey); return res.redirect(`https://docs.foo.com#${jwt}`); } ``` ### Conservar anclas de página Para redirigir a los usuarios a secciones específicas después de iniciar sesión, usa este formato de URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. **Ejemplo**: * URL original: `https://docs.foo.com/quickstart#step-one` * URL de redirección: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` ### Requisitos previos * Un servidor OAuth que sea compatible con el flujo de código de autorización con PKCE * Capacidad para crear un endpoint de API accesible mediante tokens de acceso de OAuth ### Implementación Crea un endpoint de API que: * Acepte tokens de acceso de OAuth para la autenticación. * Devuelva datos de usuario en el formato `User`. Consulta la sección [User data format](#user-data-format) más arriba para obtener más información. * Defina los scopes (alcances) de acceso. 1. En tu panel, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Selecciona **Personalization**. 3. Selecciona **OAuth** y configura estos campos: * **Authorization URL**: Tu endpoint de autorización de OAuth. * **Client ID**: Tu identificador de cliente de OAuth 2.0. * **Scopes**: Permisos a solicitar. Copia la cadena de scope **completa** (por ejemplo, para un scope como `provider.users.docs`, copia el `provider.users.docs` completo). Debe coincidir con los scopes del endpoint que configuraste en el primer paso. * **Token URL**: Tu endpoint de intercambio de tokens de OAuth. * **Info API URL**: Endpoint para recuperar datos de usuario para la personalización. Creado en el primer paso. 4. Selecciona **Save changes** 1. Copia la **Redirect URL** desde tu [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Agrega esta URL como una URL de redirección autorizada en la configuración de tu servidor OAuth. ### Ejemplo Tu documentación está alojada en `foo.com/docs` y tienes un servidor OAuth existente que admite el flujo PKCE. Quieres personalizar tu documentación en función de los datos del usuario. **Crea un endpoint de información de usuario** en `api.foo.com/docs/user-info`, que requiere un token de acceso de OAuth con el scope `provider.users.docs` y responde con los datos personalizados del usuario: ```json { "content": { "firstName": "Jane", "lastName": "Doe" }, "groups": ["ingeniería", "administración"] } ``` **Configura los detalles de tu servidor OAuth** en tu panel: * **URL de autorización**: `https://auth.foo.com/authorization` * **ID de cliente**: `ydybo4SD8PR73vzWWd6S0ObH` * **Ámbitos (scopes)**: `['docs-user-info']` * **URL de token**: `https://auth.foo.com/exchange` * **URL de la API de información**: `https://api.foo.com/docs/user-info` **Configura tu servidor OAuth** para permitir redirecciones a tu URL de retorno (callback). ### Requisitos previos * Un panel o portal de usuario con autenticación de sesión basada en cookies. * Capacidad para crear un endpoint de API en el mismo origen o subdominio que su panel. * Si su panel está en `foo.com`, la **URL de la API** debe comenzar con `foo.com` o `*.foo.com`. * Si su panel está en `dash.foo.com`, la **URL de la API** debe comenzar con `dash.foo.com` o `*.dash.foo.com`. * Su documentación está alojada en el mismo dominio o subdominio que su panel. * Si su panel está en `foo.com`, su **documentación** debe estar alojada en `foo.com` o `*.foo.com`. * Si su panel está en `*.foo.com`, su **documentación** debe estar alojada en `foo.com` o `*.foo.com`. ### Implementación Cree un endpoint de API que: * Use su autenticación de sesión existente para identificar a los usuarios * Devuelva los datos del usuario en el formato `User` (consulte la sección [User data format](#user-data-format) arriba) * Si el dominio de la API y el dominio de la documentación **no coinciden exactamente**: * Agregue el dominio de la documentación al encabezado `Access-Control-Allow-Origin` de su API (no debe ser `*`). * Establezca el encabezado `Access-Control-Allow-Credentials` de su API en `true`. Habilite los encabezados CORS solo en este endpoint específico, no en toda la API de su panel. 1. En su panel, vaya a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Seleccione **Personalization**. 3. Seleccione **Shared Session**. 4. Ingrese su **Info API URL**, que es el endpoint del primer paso. 5. Ingrese su **Login URL**, donde los usuarios inician sesión en su panel. 6. Seleccione **Save changes**. ### Ejemplos #### Panel en subdominio, documentación en subdominio Tiene un panel en `dash.foo.com`, que usa autenticación de sesión basada en cookies. Las rutas de la API de su panel están alojadas en `dash.foo.com/api`. Desea configurar la personalización para su documentación alojada en `docs.foo.com`. **Proceso de configuración**: 1. **Cree el endpoint** `dash.foo.com/api/docs/user-info` que identifique a los usuarios mediante la autenticación de sesión y responda con sus datos de usuario. 2. **Agregue encabezados CORS** solo para esta ruta: * `Access-Control-Allow-Origin`: `https://docs.foo.com` * `Access-Control-Allow-Credentials`: `true` 3. **Configure la URL de la API** en la configuración de autenticación: `https://dash.foo.com/api/docs/user-info`. #### Panel en subdominio, documentación en raíz Tiene un panel en `dash.foo.com`, que usa autenticación de sesión basada en cookies. Las rutas de la API de su panel están alojadas en `dash.foo.com/api`. Desea configurar la personalización para su documentación alojada en `foo.com/docs`. **Proceso de configuración**: 1. **Cree el endpoint** `dash.foo.com/api/docs/user-info` que identifique a los usuarios mediante la autenticación de sesión y responda con sus datos de usuario. 2. **Agregue encabezados CORS** solo para esta ruta: * `Access-Control-Allow-Origin`: `https://foo.com` * `Access-Control-Allow-Credentials`: `true` 3. **Configure la URL de la API** en la configuración de autenticación: `https://dash.foo.com/api/docs/user-info`. #### Panel en raíz, documentación en raíz Tiene un panel en `foo.com/dashboard`, que usa autenticación de sesión basada en cookies. Las rutas de la API de su panel están alojadas en `foo.com/api`. Desea configurar la personalización para su documentación alojada en `foo.com/docs`. **Proceso de configuración**: 1. **Cree el endpoint** `foo.com/api/docs/user-info` que identifique a los usuarios mediante la autenticación de sesión y responda con sus datos de usuario. 2. **Configure la URL de la API** en la configuración de autenticación: `https://foo.com/api/docs/user-info` No se necesita configuración de CORS, ya que el panel y la documentación comparten el mismo dominio.