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.
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
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.
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.
2
Distribuye el acceso.
Comparte de forma segura la contraseña y la URL de la documentación con los usuarios autorizados.
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.
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.
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.
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.
Agrega la Redirect URL como una URL de redirección autorizada en tu servidor OAuth.
3
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: 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.
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:
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:
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.
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.
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.
2
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.
Si tu organización tiene más de un proveedor de identidad o un flujo de inicio de sesión específico por región, puedes configurar entre 2 y 10 URL de inicio de sesión con nombre para tu sitio con autenticación JWT. Cuando se configura más de una URL, los visitantes no autenticados ven una pantalla de selección de inicio de sesión con la marca de tu sitio, y cada opción redirige a la URL que configuraste.Para configurar varias URL de inicio de sesión, proporciona una lista de pares { name, url } al actualizar la configuración de autenticación JWT. Cada nombre se muestra a los usuarios en la pantalla de selección y debe tener entre 1 y 100 caracteres. Cada URL debe ser una URL válida. Con una sola URL de inicio de sesión, los visitantes siguen siendo redirigidos directamente a esa URL como antes.
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}`);}
import jwt # pyjwtimport osfrom datetime import datetime, timedeltafrom fastapi.responses import RedirectResponseprivate_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')DOCS_HOST = 'docs.example.com'@router.get('/auth')async def return_mintlify_auth_status(current_user): jwt_token = jwt.encode( payload={ 'host': DOCS_HOST, # Debe coincidir con la URL de tu documentación 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # vencimiento del JWT de 10 segundos 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # vencimiento de la sesión de 2 semanas 'groups': ['admin'] if current_user.is_admin else [], 'apiPlaygroundInputs': { 'header': { 'Authorization': f'Bearer {current_user.api_key}', }, }, }, key=private_key, algorithm='EdDSA' ) return RedirectResponse(url=f'https://{DOCS_HOST}/login/jwt-callback#{jwt_token}', status_code=302)
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}.
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.
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.
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.
Cuando utilices autenticación OAuth o JWT, 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.
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.
Momento de expiración de la sesión en segundos desde el epoch. Cuando la hora actual supera este valor, el usuario debe volver a autenticarse.
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).
Lista de los grupos a los que pertenece el usuario. Las páginas cuyo frontmatter tenga un groups coincidente son accesibles para este usuario.Ejemplo: Un usuario con groups: ["admin", "engineering"] puede acceder a páginas etiquetadas con los grupos admin o engineering.
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.
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)