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.

¡Bienvenido/a de nuevo, {user.firstName}! Tu plan {user.org?.plan} incluye...

Consulta la sección Formato de datos de usuario 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.

---
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.

type User = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};

expiresAt · number

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.

groups · string[]

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.

content · object

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:

{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }

Uso en 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:

Authentication is an enterprise feature. {
  user.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : user.org.plan !== 'enterprise'
      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> 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}.

apiPlaygroundInputs · object

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:

{
  "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. 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

{
  "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.

JWT

​

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. Generate a private key.

   1. En tu panel, ve a 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.
2. Integrate Mintlify personalization into your login flow.

   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 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}.

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

OAuth 2.0

​

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

1. Create user info API endpoint.

   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 más arriba para obtener más información.
   • Defina los scopes (alcances) de acceso.
2. Configure your OAuth personalization settings.

   1. En tu panel, ve a 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
3. Configure your OAuth server.

   1. Copia la Redirect URL desde tu authentication settings.
   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:

{
  "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).

Sesión compartida

​

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

1. Create user info API endpoint.

   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 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.

2. Configure your personalization settings

   1. En su panel, vaya a 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.