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