Saltar al contenido principal
La personalización adapta tu documentación para cada usuario cuando inicia sesión. Por ejemplo, puedes rellenar 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 opciones de personalización.

​
Prefill automático de API key

Rellena automáticamente los campos del área de pruebas de la API con valores específicos del usuario devolviendo nombres de campos que coincidan en tus datos de usuario. Los nombres de campos en tus datos de usuario deben coincidir exactamente con los nombres del área de pruebas de la API para que el prefill automático funcione.

​
Contenido dinámico en MDX

Muestra contenido dinámico según la información del usuario, como el nombre, el plan o la organización, usando la variable user. 
¡Bienvenido de vuelta, {user.firstName}! Tu plan {user.org?.plan} incluye...
Consulta la sección Formato de datos del usuario a continuación 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, todas las páginas son visibles para todos los usuarios. Los usuarios solo verán las páginas de los groups a los que pertenecen. 
---
title: "Gestión de tus usuarios"
description: "Agregar y eliminar usuarios de tu organización"
groups: ["admin"]
---

​
Formato de datos de usuario

Al implementar la personalización, tu sistema devuelve los datos de usuario en un formato específico que permite la personalización del contenido. Estos datos se pueden enviar como un objeto JSON bruto o dentro de un JWT firmado, según tu método de handshake. 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 la época Unix. 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 es distinto del claim exp del JWT, que determina cuándo un JWT se considera inválido. Por seguridad, configura el claim exp del JWT con una duración corta (10 segundos o menos). Usa expiresAt para la duración real de la sesión (de horas a semanas).
​
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 a través de la variable user. Úsalos para realizar 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 el ejemplo de datos de user, esto 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 con sesión iniciada. Para usuarios sin iniciar sesión, el valor de user será {}. Para evitar que la página falle para usuarios sin iniciar sesión, usa siempre encadenamiento opcional en los campos de user. Por ejemplo, {user.org?.plan}.
​
apiPlaygroundInputs
object
Valores específicos del usuario que rellenan previamente los campos del área de pruebas de la 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 realiza solicitudes en un subdominio específico, puedes enviar { server: { subdomain: 'foo' } } como un campo apiPlaygroundInputs. Este valor se rellenará previamente en cualquier página de la API con el valor subdomain.
Los campos header, query y cookie solo se rellenarán previamente si forman parte de tu esquema de seguridad de OpenAPI. Si un campo está en las secciones Authorization o Server, se rellenará previamente. Crear un parámetro de encabezado estándar llamado Authorization no habilitará esta función.

​
Ejemplo de datos de usuario

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

​
Requisitos previos

  • Un sistema de inicio de sesión que pueda generar y firmar JWT
  • Un servicio backend que pueda crear URL de redirección

​
Implementación

1

Genera una key privada.

  1. En tu dashboard, ve a Autenticación.
  2. Selecciona Personalization.
  3. Selecciona JWT.
  4. Ingresa la URL de tu flujo de inicio de sesión existente y selecciona Guardar cambios.
  5. Selecciona Generate new key.
  6. Almacena tu key de forma segura donde pueda accederla tu backend.
2

Integra la personalización de Mintlify en tu flujo de inicio de sesión.

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 que ha iniciado sesión 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 vuelta 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 dashboard (o no tienes un dashboard) y habilitar la personalización.Genera un secreto 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 de 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 anclajes 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