Configuración de autenticación

Configura la autenticación de usuarios para controlar el acceso a páginas y referencias de API con contraseña, OAuth, JWT o acceso privado en Mintlify.

La autenticación privada para tu organización de Mintlify está disponible en todos los planes.

La autenticación por contraseña requiere un plan Pro o Enterprise.

La autenticación con OAuth y JWT requiere un plan Enterprise.

La autenticación exige que los usuarios inicien sesión antes de acceder a tu contenido.

Puedes configurar autenticación completa para todas las páginas o autenticación parcial en la que algunas páginas son públicas y otras requieren autenticación.

La autenticación solo está disponible para sitios alojados en un dominio personalizado o subdominio de Mintlify. Por ejemplo, docs.ejemplo.com o ejemplo.mintlify.site. La autenticación no es compatible para sitios con una subruta personalizada. Por ejemplo, ejemplo.com/docs.

Para identificar a los visitantes sin dejar de mantener las páginas públicas, usa la personalización. La personalización admite subrutas personalizadas y puede rellenar previamente los campos del área de pruebas de la API sin exigir a los visitantes que se autentiquen antes de ver una página.

Elige un método de autenticación

Usa esta comparación para elegir el método que se adapte a tu caso de uso. Consulta Disponibilidad de funciones para ver cómo interactúa cada método con otras funciones de Mintlify.

Método	Ideal para	Plan	Control de acceso basado en grupos	Autocompletado del área de pruebas de la API	Personalización
Contraseña	Acceso compartido sencillo sin seguimiento por usuario	Pro o Enterprise	—	—	—
Autenticación privada	Documentación interna para miembros de tu organización de Mintlify	Todos los planes	—	—	—
OAuth 2.0	Proveedor de identidad existente o SSO con sesiones por usuario	Enterprise	✓	✓	✓
JWT	Backend de autenticación personalizado o documentación integrada detrás de tu propio inicio de sesión	Enterprise	✓	✓	✓

Configurar la autenticación

La autenticación mediante contraseña proporciona únicamente control de acceso y no admite funciones específicas por usuario, como el control de acceso basado en grupos o el autocompletado previo del área de pruebas de la API.

Requisitos previos de la contraseña

Tus requisitos de seguridad permiten compartir contraseñas entre usuarios.

Configuración de la contraseña

Crea una contraseña.

En tu dashboard, ve a Authentication.
En la sección Authentication method, establece la visibilidad del sitio en Private.
Haz clic en Password.
Introduce una contraseña segura.
Haz clic en Save changes.

Después de guardar, tu sitio se vuelve a implementar automáticamente. Cuando la implementación haya finalizado, cualquiera que visite tu sitio deberá introducir la contraseña para acceder a tu contenido.

Distribuye el acceso.

Comparte de forma segura la contraseña y la URL de la documentación con los usuarios autorizados.

Ejemplo de contraseña

Alojas tu documentación en docs.foo.com y necesitas un control de acceso básico sin hacer seguimiento de usuarios individuales. Quieres evitar el acceso público sin complicar la configuración.

Crea una contraseña segura en tu dashboard. Comparte las credenciales con los usuarios autorizados.

Requisitos previos de la autenticación privada

Todas las personas que necesiten acceder a tu sitio deben ser miembros de tu organización de Mintlify.

Configuración de la autenticación privada

Habilita la autenticación privada.

En tu dashboard, ve a Authentication.
En la sección Authentication method, establece la visibilidad del sitio en Private.
Haz clic en Authenticated.
Haz clic en Save changes.

Después de guardar, tu sitio se vuelve a implementar automáticamente. Una vez que finalice la implementación, cualquier persona que visite tu sitio deberá iniciar sesión en tu organización de Mintlify para acceder a tu contenido.

Agrega usuarios autorizados.

En tu dashboard, ve a Members.
Agrega a cada persona que deba tener acceso a tu documentación.
Asigna los roles apropiados según sus permisos de edición.

Ejemplo de autenticación privada

Alojas tu documentación en docs.foo.com y todo tu equipo tiene acceso a tu dashboard. Quieres restringir el acceso solo a los miembros del equipo.

Habilita la autenticación privada en la configuración de tu dashboard.

Verifica el acceso del equipo comprobando que todos los miembros del equipo estén activos en tu organización.

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

Configuración de OAuth 2.0

Configura tus ajustes de OAuth.

En tu dashboard, ve a Authentication.
En la sección Authentication method, establece la visibilidad del sitio en Private.
Haz clic en Custom
Haz clic en OAuth.
Configura estos campos:

Authorization URL: Tu endpoint de OAuth.
Client ID: Tu identificador de cliente de OAuth 2.0.
Client Secret: Tu secreto de cliente de OAuth 2.0.
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. Usa este campo para el enfoque de Info API para el control de acceso basado en grupos. También puedes usar los claims de OAuth. Si no configuras ninguno de los dos, 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.

Haz clic en Guardar cambios.

Después de configurar tus ajustes de OAuth, tu sitio se vuelve a implementar. Cuando finalice la implementación, cualquier persona que visite tu sitio deberá iniciar sesión en tu proveedor de OAuth para acceder a tu contenido.

Configura tu servidor OAuth.

Copia la Redirect URL de tus ajustes de autenticación.
Agrega la Redirect URL como una URL de redirección autorizada en tu servidor OAuth.

Crea tu endpoint de información de usuario para el acceso por grupos (opcional).

Para usar el enfoque de Info API para el control de acceso basado en grupos, crea un endpoint de API que:

Responda a solicitudes GET.
Acepte un encabezado Authorization: Bearer <access_token> para la autenticación.
Devuelva los datos de usuario en el formato User. Consulta Formato de datos de usuario para obtener más información.

Mintlify llama a este endpoint con el token de acceso de OAuth para obtener la información del usuario. No se envían parámetros de consulta adicionales.

Agrega la URL de este endpoint al campo Info API URL en tus ajustes de autenticación.

Usa los grupos incluidos en los claims del token de OAuth

Si tu proveedor de identidad incluye la pertenencia a grupos en el token de ID o en el token de acceso, puedes usar esos claims en lugar de una URL de Info API. Esta opción está disponible para configuraciones de OAuth que usan un secreto de cliente.

Al configurar los claims del token de OAuth para tu implementación, usa valores como estos:

{
  "source": "id_token",
  "groupsClaim": "groups",
  "groupsDelimiter": ","
}

source: Selecciona id_token o access_token. Si seleccionas id_token, incluye el scope openid en tus scopes de OAuth.
groupsClaim: Identifica el claim del token que contiene los grupos. El valor predeterminado de groupsClaim es groups.
groupsDelimiter: Delimitador opcional de 1 a 4 caracteres. Mintlify solo lo usa para dividir los valores de los claims que sean cadenas.

Por ejemplo, con "groups": "general,clienta_eur" y groupsDelimiter establecido en ",", Mintlify usa general y clienta_eur como grupos separados.

Mintlify elimina los espacios en blanco alrededor de cada grupo e ignora los segmentos vacíos. Sin groupsDelimiter, la cadena completa se trata como un solo grupo. Los claims que son arrays siempre se tratan como un grupo por cada elemento de cadena y no se dividen.

Omite groupsDelimiter cuando el delimitador pueda formar parte del nombre de un grupo.

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

Configura los detalles de tu servidor OAuth en tu dashboard:

Authorization URL: https://auth.foo.com/authorization
Client ID: ydybo4SD8PR73vzWWd6S0ObH
Scopes: ['provider.users.docs']
Token URL: https://auth.foo.com/exchange
Info API URL: https://api.foo.com/docs/user-info
Logout URL: https://auth.foo.com/logout?returnTo=https%3A%2F%2Fdocs.foo.com

Crea un endpoint de información de usuario en api.foo.com/docs/user-info, que requiera un token de acceso OAuth con el scope provider.users.docs, y devuelva:

{
  "groups": ["engineering", "admin"],
  "expiresAt": 1893456000,
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

Controla la duración de la sesión con el campo expiresAt en la respuesta de información de usuario. Este es un timestamp Unix (segundos desde el inicio de la época Unix) que indica cuándo debe expirar la sesión. Consulta Formato de datos de usuario para más detalles.

Configura tu servidor OAuth para permitir redirecciones a tu URL de callback.

Requisitos previos de JWT

Un sistema de autenticación que pueda generar y firmar JWT.
Un servicio de backend que pueda crear URL de redirección.

Configuración de JWT

Genera una clave privada.

En tu dashboard, ve a Authentication.
En la sección Authentication method, establece la visibilidad del sitio en Private.
Haz clic en Custom
Haz clic en JWT.
Introduce la URL de tu flujo de inicio de sesión existente.
Para ofrecer más de un flujo de inicio de sesión, haz clic en Add login URL e introduce un nombre visible y una URL para cada opción. Puedes configurar hasta 10 URL de inicio de sesión.
Haz clic en Save changes.
Haz clic en Generate new key.
Almacena tu clave de forma segura donde tu backend pueda acceder a ella.

Después de generar una clave privada, tu sitio se vuelve a implementar automáticamente. Cuando la implementación haya finalizado, cualquier persona que visite tu sitio debe iniciar sesión en tu sistema de autenticación JWT para acceder a tu contenido.

Integra la autenticació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 la autenticación del usuario:

Crea un JWT que contenga la información del usuario autenticado en el formato User. Consulta Formato de datos de usuario para obtener más información.
Firma el JWT con tu clave secreta, usando el algoritmo EdDSA.
Crea una URL de redirección de vuelta a la ruta /login/jwt-callback de tu documentación, incluyendo el JWT como el hash.

Cuando la autenticación con JWT tiene una única URL de inicio de sesión, los visitantes no autenticados se redirigen a ella automáticamente. Con dos o más URL de inicio de sesión con nombre, los visitantes primero ven una página de selección y luego continúan al flujo de inicio de sesión elegido. Mintlify reenvía el parámetro redirect validado para que el visitante regrese a la página de documentación que solicitó originalmente.

Las múltiples URL de inicio de sesión están disponibles para la autenticación JWT completa y parcial. La personalización con JWT admite una única URL de inicio de sesión porque identifica a los visitantes sin exigirles iniciar sesión antes de ver contenido público.

Ejemplo de JWT

Alojas tu documentación en docs.foo.com con un sistema de autenticación existente en foo.com. Quieres ampliar tu flujo de inicio de sesión para conceder acceso a la documentación manteniéndola separada de tu dashboard (o no tienes un dashboard).

Crea un endpoint de inicio de sesión en https://foo.com/docs-login que amplíe tu autenticación existente.

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/login/jwt-callback#{SIGNED_JWT}.

import * as jose from 'jose';
import { Request, Response } from 'express';

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const DOCS_HOST = 'docs.example.com';

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    host: DOCS_HOST, // Debe coincidir con la URL de tu documentación
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // vencimiento de la sesión de 2 semanas
    groups: res.locals.user.groups,
    apiPlaygroundInputs: {
      header: {
        "Authorization": `Bearer ${res.locals.user.apiKey}`,
      },
    },
  };

  const jwt = await new jose.SignJWT(user)
    .setProtectedHeader({ alg: 'EdDSA' })
    .setExpirationTime('10 s') // vencimiento del JWT de 10 segundos
    .sign(signingKey);

  return res.redirect(`https://${DOCS_HOST}/login/jwt-callback#${jwt}`);
}

Redirigir a usuarios no autenticados

Cuando un usuario no autenticado intenta acceder a una página protegida, la redirección a tu URL de inicio de sesión conserva el destino previsto del usuario.

El usuario intenta visitar una página protegida: https://docs.foo.com/quickstart.
Redirige a tu URL de inicio de sesión con un parámetro de consulta llamado redirect: https://foo.com/docs-login?redirect=%2Fquickstart.
Después de la autenticación, redirige a https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}.
El usuario llega a su destino original.

Hacer públicas las páginas

Cuando uses Autenticación, todas las páginas están protegidas de forma predeterminada. Puedes hacer que páginas específicas sean visibles sin autenticación a nivel de página o de grupo con la propiedad public.

Páginas individuales

Para hacer pública una página, agrega public: true al frontmatter de la página.

Public page example

---
title: "Página pública"
public: true
---

Grupos de páginas

Para hacer públicas todas las páginas de un grupo, añade "public": true debajo del nombre del grupo en el objeto navigation de tu docs.json.

Public group example

{
  "navigation": {
    "groups": [
      {
        "group": "Grupo público",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "Grupo privado",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}

Controla el acceso con groups

Cuando usas OAuth o autenticación con JWT (JSON Web Token), puedes restringir páginas específicas a ciertos grupos de usuarios. Esto es útil cuando quieres que distintos usuarios vean contenido diferente según su rol o atributos.

Administra los grupos mediante los datos del usuario enviados durante la autenticación. Consulta Formato de datos de usuario para más detalles.

Example user info

{
  "groups": ["admin", "beta-users"],
  "expiresAt": 1893456000
}

Especifica qué groups pueden acceder a páginas determinadas usando la propiedad groups en el frontmatter.

Example page restricted to the admin group

---
title: "Panel de administración"
groups: ["admin"]
---

Los usuarios deben pertenecer al menos a uno de los groups enumerados para acceder a la página. Si un usuario intenta acceder a una página sin el group requerido, recibirá un error 404.

Cómo interactúan los groups con las páginas públicas

Todas las páginas requieren Autenticación de forma predeterminada.
Las páginas con una propiedad groups solo son accesibles para usuarios autenticados dentro de esos groups.
Las páginas sin la propiedad groups son accesibles para todos los usuarios autenticados.
Las páginas con public: true y sin la propiedad groups son accesibles para cualquier persona.

---
title: "Guía pública"
public: true
---

Formato de datos de usuario

Cuando utilices autenticación OAuth o JWT o personalización independiente, tu sistema devolverá datos de usuario que controlan la duración de la sesión, la pertenencia a grupos y la personalización de contenido.

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

hoststring

Obligatorio para la autenticación JWT. El nombre de host de tu sitio de documentación. La cadena debe coincidir exactamente con el dominio donde implementas tu documentación. Mintlify valida que el host del JWT coincida con el host de la solicitud para evitar la reutilización de tokens entre diferentes sitios.

expiresAtnumber

Momento de expiración de la sesión en segundos desde el epoch. Cuando la hora actual supera este valor, Mintlify expira los datos de usuario almacenados. El visitante debe autenticarse de nuevo o repetir el flujo de identificación para actualizarlos.

Para JWT: Esto es diferente del claim exp del JWT, que determina cuándo un JWT se considera inválido. Configura el claim exp del JWT con una duración corta (10 segundos o menos) por seguridad. Usa expiresAt para la duración real de la sesión (de horas a semanas).

groupsstring[]

Lista de los grupos a los que pertenece el usuario. Con autenticación, las páginas cuyo frontmatter tenga un groups coincidente son accesibles para este usuario. Con la personalización independiente, groups controla la visibilidad de páginas y contenido, pero no restringe el acceso a la URL directa de una página.

Ejemplo: Un usuario con groups: ["admin", "engineering"] coincide con el contenido etiquetado con los grupos admin o engineering.

contentRecord<string, any>

Datos personalizados accesibles en páginas MDX mediante la variable user para contenido personalizado.

apiPlaygroundInputsobject

Rellena previamente los campos del área de pruebas de la API con valores específicos del usuario. Cuando un usuario se autentica, estos valores rellenan los campos de entrada correspondientes en el área de pruebas de la API. Los usuarios pueden sobrescribir los valores rellenados previamente, y sus cambios persisten en el almacenamiento local.

Mintlify aplica únicamente los valores que coinciden con el esquema de seguridad del endpoint actual.

Show propiedades

headerRecord<string, unknown>

Valores de encabezado que se van a rellenar previamente, indexados por nombre de encabezado.

queryRecord<string, unknown>

Valores de parámetros de búsqueda que se van a rellenar previamente, indexados por nombre de parámetro.

cookieRecord<string, unknown>

Valores de cookies que se van a rellenar previamente, indexados por nombre de cookie.

serverRecord<string, string>

Valores de variables de servidor que se van a rellenar previamente, indexados por nombre de variable.

pathRecord<string, unknown>

Valores de parámetros de ruta que se van a rellenar previamente, indexados por nombre de parámetro.

Disponibilidad de funciones

Algunas funciones se comportan de manera diferente o no están disponibles cuando habilitas la autenticación. Mintlify no admite el alojamiento público de archivos arbitrarios en un sitio autenticado. Todos los archivos alojados, incluidos llms.txt, llms-full.txt y skill.md, están sujetos a los mismos requisitos de autenticación que las páginas de tu documentación.

Función	Público	Totalmente autenticado (todas las páginas protegidas)	Parcialmente autenticado (algunas páginas públicas)
llms.txt and llms-full.txt	Compatibilidad completa	Disponible tras autenticación, por lo que es posible que las herramientas de IA no puedan acceder a los archivos	Disponible tras autenticación, por lo que es posible que las herramientas de IA no puedan acceder a los archivos
Servidor MCP	Compatibilidad completa	Requiere autenticación para conectarse	Disponible sin autenticación para páginas públicas y con autenticación para páginas protegidas
Exportación a Markdown	Compatibilidad completa	Compatibilidad completa, respeta los grupos de usuarios	Compatibilidad completa, respeta los grupos de usuarios
Exportación a PDF	Compatibilidad completa	Compatibilidad completa, respeta los grupos de usuarios. Las páginas autenticadas se exportan con imágenes y recursos incluidos.	Compatibilidad completa, respeta los grupos de usuarios. Las páginas autenticadas se exportan con imágenes y recursos incluidos.
Búsqueda	Compatibilidad completa	Compatibilidad completa, respeta los grupos de usuarios	Compatibilidad completa, respeta los grupos de usuarios
Assistant	Compatibilidad completa	Compatibilidad completa, respeta los grupos de usuarios	Compatibilidad completa, respeta los grupos de usuarios
skill.md	Compatibilidad completa	No compatible	No compatible
Mapa del sitio	Compatibilidad completa	Disponible tras autenticación, pero excluye las páginas en groups	Disponible tras autenticación, pero excluye las páginas en groups
robots.txt	Compatibilidad completa	Disponible tras autenticación	Disponible tras autenticación
Vista previa en vivo	Compatibilidad completa	Compatible con autenticación automática del editor	Compatible con autenticación automática del editor

Configuración de autenticación

On this page