Cómo configurar el acceso restringido y la autenticación de usuarios en Mintlify para documentación de API privada

Los equipos de ingeniería y arquitectos de plataformas de desarrollo que gestionan documentación de API privadas para clientes empresariales, socios comerciales o integraciones internas se enfrentan a un desafío constante: ofrecer una experiencia de desarrollo interactiva y moderna con consolas de prueba de API funcionales, al tiempo que aíslan de forma estricta los endpoints críticos, SDK propietarios y servicios de facturación frente a accesos no autorizados e indexadores públicos.

Mintlify resuelve esta necesidad combinando su motor basado en MDX y OpenAPI con cuatro mecanismos de control de acceso: protección interna de organización, restricción global por contraseña, inicio de sesión único empresarial (SSO / OAuth 2.0) y autenticación mediante JSON Web Tokens (JWT) firmados. Esta guía detalla los requisitos de arquitectura, flujos de configuración, políticas de control de acceso basado en roles (RBAC) a nivel de página y la inyección segura de credenciales en el API Playground para entornos de producción.

Requisitos de arquitectura y restricciones de dominio

Antes de configurar cualquier mecanismo de autenticación, los equipos técnicos deben considerar las directrices de despliegue de Mintlify:

1. Requisito de dominio exclusivo: El control de acceso y la autenticación de usuarios (tanto total como parcial) requieren que la documentación esté alojada en un dominio personalizado dedicado (como docs.api.example.com) o en un subdominio de Mintlify (example.mintlify.site). El acceso restringido no es compatible con despliegues en subrutas (como example.com/docs). Para subrutas solo es posible aplicar personalización sin bloqueo estricto de acceso.
2. Alcance del control (Total vs. Parcial): Es posible configurar una Autenticación Total (Full) (bloqueando todo el portal y las especificaciones OpenAPI tras un inicio de sesión obligatorio) o una Autenticación Parcial (Partial) (manteniendo públicas las guías de inicio rápido y protegiendo exclusivamente los endpoints empresariales y módulos internos).
3. Seguridad en despliegues de prueba (Preview Deployments): En flujos de trabajo basados en Git, los enlaces de vista previa generados por Pull Requests pueden exponer interfaces privadas si no están protegidos. Al activar la autenticación en Mintlify, todos los entornos de vista previa heredan automáticamente las políticas de seguridad.

Matriz comparativa de métodos de autenticación

Método 1: Protección por contraseña (Acceso restringido rápido)

La protección por contraseña ofrece una barrera inmediata para pruebas preliminares con socios estratégicos o revisiones confidenciales sin necesidad de integrar un proveedor de identidad.

Pasos de configuración

1. Acceda al panel de control en Mintlify Dashboard y seleccione la pestaña Access.
2. Cambie Visibility de Public a Private.
3. En Method, seleccione Password.
4. Introduzca una contraseña compartida de alta seguridad y guarde los cambios con Save changes.

Consideraciones técnicas

Aunque este método se configura en dos minutos, todos los usuarios comparten la misma credencial. No permite auditar la actividad de usuarios individuales, segmentar permisos por roles ni revocar el acceso a un colaborador específico sin cambiar la contraseña de todos los demás. Se recomienda únicamente para fases beta tempranas y demostraciones controladas.

Método 2: SSO empresarial y OAuth 2.0 (Federación de identidad)

Para portales internos o documentación dirigida a grandes clientes corporativos, federar la identidad mediante SAML 2.0 u OAuth 2.0 garantiza cumplimiento normativo, aprovisionamiento automático y revocación instantánea de accesos.

Configuración con Okta SAML 2.0

1. Obtener parámetros de Mintlify: En el panel de Mintlify, acceda a Security, haga clic en Configure y seleccione Okta SAML. Copie la Single sign on URL (URL de ACS) y la Audience URI (SP Entity ID).
2. Crear la aplicación SAML en el IdP: En la consola de Okta, diríjase a Applications > Create App Integration > SAML 2.0. Pegue la URL y el URI proporcionados por Mintlify.
3. Mapear atributos de usuario: Configure las declaraciones de atributos requeridas:
   • firstName -> user.firstName
   • lastName -> user.lastName
   • Name -> user.email (con formato de Name ID en EmailAddress).
4. Vincular metadatos: Copie la Metadata URL de la aplicación en Okta, péguela en el campo correspondiente del panel de Mintlify y guarde los cambios.

Una vez activado, cualquier usuario que visite el dominio de documentación será redirigido a la pasarela de autenticación corporativa antes de visualizar las especificaciones de API privadas.

Método 3: Autenticación personalizada mediante JWT (Integración fluida)

En plataformas SaaS comerciales, los clientes ya han iniciado sesión en el panel principal de su producto. Para evitar un segundo inicio de sesión al consultar la documentación privada, Mintlify permite enlazar la sesión mediante JWT firmados asimétricamente.

Flujo de interacción

Navegador del cliente          Backend de su plataforma (App)       Documentación Mintlify
         |                                |                                   |
         | 1. Clic en "Documentación API"  |                                   |
         |------------------------------->|                                   |
         |                                | 2. Genera payload con roles y     |
         |                                |    firma JWT con clave ES256      |
         | 3. Redirige a la documentación  |                                   |
         |    https://docs.example.com/#JWT|                                  |
         |<-------------------------------|                                   |
         |                                                                    |
         | 4. Solicita página con JWT en el fragmento (Hash) de la URL        |
         |------------------------------------------------------------------->|
         |                                | 5. Valida firma ES256, aplica     |
         |                                |    permisos y elimina el Hash     |
         | 6. Renderiza endpoints privados y Playground con credenciales      |
         |<-------------------------------------------------------------------|

Pasos de implementación

1. En el panel de Mintlify, vaya a la configuración de Access (o Personalization), elija JWT e ingrese la URL de inicio de sesión de su aplicación.
2. Genere un par de claves criptográficas en el panel y almacene la clave privada en un gestor de secretos seguro (como AWS Secrets Manager o KMS).
3. En su backend, construya un JWT firmado con el algoritmo ES256 que contenga los permisos de grupo y los datos de sesión:

import jwt from "jsonwebtoken";

// Ejemplo en Node.js para firmar el token de acceso a Mintlify
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // Declaraciones estándar de JWT
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // Expiración corta: 10 segundos o menos
    
    // Duración de la sesión en el portal de Mintlify
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8 horas de sesión
    
    // Contexto de usuario para renderizado condicional en MDX
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // Ej: "enterprise" o "growth"
    },
    
    // Grupos para filtrado de navegación y control de acceso
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // Credenciales para autorrellenar el API Playground
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. Al redirigir al usuario hacia la documentación, adjunte el JWT como fragmento de URL (Hash):

   https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   Mintlify extrae el token en el cliente, verifica la firma contra la clave pública registrada, inicializa la sesión y borra de inmediato el fragmento de la barra de direcciones del navegador para evitar fugas en el historial o cabeceras Referer.

Control de acceso basado en roles (RBAC) y segmentación de páginas

Una vez establecida la identidad, el equipo de ingeniería puede estructurar la visibilidad de la documentación según el nivel del cliente.

1. Restricción en el Frontmatter de archivos MDX

Defina los grupos autorizados en el encabezado YAML de los archivos .mdx protegidos:

---
title: "Webhooks de liquidación empresarial"
description: "Especificación de webhooks financieros de alto rendimiento"
groups: ["enterprise", "fintech-partners"]
---

Si el JWT o la sesión SSO del usuario no contiene el grupo requerido, Mintlify oculta automáticamente la página en la barra de navegación y bloquea el acceso directo vía URL devolviendo un estado 404 o acceso restringido.

2. Renderizado condicional en MDX mediante userContext

Para páginas compartidas que contienen secciones o cuotas específicas para clientes prémium, utilice el objeto userContext:

# Políticas de límites de velocidad

{userContext?.content?.plan === "enterprise" ? (
  <Card title="Cuota empresarial dedicada" icon="shield-check">
    Su cuenta dispone de 10.000 solicitudes por segundo con soporte técnico prioritario.
  </Card>
) : (
  <Card title="Límite estándar" icon="gauge">
    El límite estándar es de 200 peticiones por minuto. Contacte a ventas para ampliar su cuota.
  </Card>
)}

3. Aislamiento frente a agentes de IA y scrapers

Mintlify optimiza el contenido en Markdown para herramientas de IA. Si desea que ciertas instrucciones confidenciales no sean procesadas por agentes externos, utilice el componente <Visibility>:

<Visibility for="humans">
  <Note>Las claves de producción deben rotarse cada 90 días desde su panel de control.</Note>
</Visibility>

<Visibility for="agents">
  Las solicitudes a la API requieren un token Bearer en la cabecera Authorization.
</Visibility>

Seguridad en el API Playground interactivo

La consola de pruebas interactiva es una de las funciones más potentes de Mintlify, pero requiere precauciones estrictas para evitar fugas de claves maestras o modificaciones accidentales en producción.

1. Inyección segura mediante apiPlaygroundInputs

En lugar de solicitar a los desarrolladores que copien credenciales manualmente en el navegador, proporcione claves de prueba temporales vinculadas a la sesión:

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

El Playground mapeará automáticamente estos valores a las cabeceras y parámetros correspondientes al cargar la interfaz.

2. Reglas de seguridad imprescindibles

• Aislar entornos de prueba y Mock: Asegúrese de que las URLs de servidor en docs.json apunten por defecto a entornos sandbox o servidores mock, nunca a clústeres de producción directa.
• Evitar la inyección de claves maestras permanentes: Las credenciales suministradas en apiPlaygroundInputs deben ser efímeras y tener permisos estrictamente acotados a pruebas.
• Utilizar x-default en OpenAPI para plantillas: En páginas públicas o protegidas por contraseña sin JWT dinámico, defina marcadores de posición en securitySchemes (por ejemplo, x-default: "SU_CLAVE_SANDBOX") evitando incluir secretos reales en el repositorio de código.

Lista de verificación previa al lanzamiento

• Alineación de dominio: Documentación alojada en un subdominio dedicado (docs.partner.example.com) y no en una subruta (/docs).
• Definición del alcance: Configurado el modo de autenticación adecuado (Full o Partial) en el panel Access.
• Custodia de claves: Clave privada de firma ES256 resguardada en KMS o gestor de secretos, fuera del control de versiones.
• Vigencia mínima del token: Atributo exp del JWT establecido en 10 segundos o menos para prevenir ataques de repetición.
• Etiquetado de grupos: Páginas y endpoints confidenciales marcados con etiquetas groups en sus archivos MDX.
• Configuración del Playground: Servidores por defecto apuntando exclusivamente a entornos de prueba seguros.
• Protección de entornos Preview: Despliegues de ramas de Git verificados con las mismas restricciones de acceso.

La implementación de este modelo permite a los equipos de ingeniería proporcionar una documentación interactiva de primer nivel para clientes estratégicos, salvaguardando al mismo tiempo la seguridad perimetral de las APIs privadas.

Referencias

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify