Authentication setup

Password prerequisites

• Your security requirements allow sharing passwords among users.

Password setup

Password example

You host your documentation at docs.foo.com and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.

Create a strong password in your dashboard. Share credentials with authorized users.

Private authentication prerequisites

• Everyone who needs to access your site must be a member of your Mintlify organization.

Private authentication setup

Private example

You host your documentation at docs.foo.com and your entire team has access to your dashboard. You want to restrict access to team members only.

Enable private authentication in your dashboard settings.

Verify team access by checking that all team members are active in your organization.

OAuth 2.0 prerequisites

• An OAuth or OIDC server that supports the Authorization Code Flow.
• Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable group-based access control).

OAuth 2.0 setup

Use groups from OAuth token claims

If your identity provider includes group membership in the ID token or access token, you can use those claims instead of an Info API URL. This option is available for OAuth configurations that use a client secret.

When configuring OAuth token claims for your project, use values such as:

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

• source: Selects id_token or access_token. If you select id_token, include the openid scope in your OAuth scopes.
• groupsClaim: Identifies the token claim that contains groups. Defaults to groups.
• groupsDelimiter: An optional delimiter from 1 to 4 characters. Mintlify uses it only to split string claim values. If the delimiter can be part of a group name, omit groupsDelimiter.

For example, with "groups": "general,client" and groupsDelimiter set to ",", Mintlify uses general and client as separate groups.

Mintlify trims whitespace around each group and ignores empty segments. Without groupsDelimiter, the complete string is a single group. Array claims are always one group per string item and are not split.

OAuth 2.0 example

You host your documentation at docs.foo.com and you have an existing OAuth server at auth.foo.com that supports the Authorization Code Flow.

Configure your OAuth server details in your 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

Create a user info endpoint at api.foo.com/docs/user-info, which requires an OAuth access token with the provider.users.docs scope, and returns:

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

Configure your OAuth server to allow redirects to your callback URL.

JWT prerequisites

• An authentication system that can generate and sign JWTs.
• A backend service that can create redirect URLs.

JWT setup

When JWT authentication has one login URL, unauthenticated visitors redirect to it automatically. With two or more named login URLs, visitors first see a selection page and then continue to the selected login flow. Mintlify forwards the validated redirect parameter so the visitor returns to the documentation page they originally requested.

JWT example

You host your documentation at docs.foo.com with an existing authentication system at foo.com. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard).

Create a login endpoint at https://foo.com/docs-login that extends your existing authentication.

After verifying user credentials:

• Generate a JWT with user data in Mintlify's format.
• Sign the JWT and redirect to 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, // Must match your docs URL
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
    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') // 10 second JWT expiration
    .sign(signingKey);

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

import jwt # pyjwt
import os

from datetime import datetime, timedelta
from fastapi.responses import RedirectResponse

private_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, # Must match your docs URL
      'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()),    # 10 second JWT expiration
      'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session expiration
      '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)

Redirect unauthenticated users

When an unauthenticated user tries to access a protected page, the redirect to your login URL preserves the user's intended destination.

1. User attempts to visit a protected page: https://docs.foo.com/quickstart.
2. Redirect to your login URL with a redirect query parameter: https://foo.com/docs-login?redirect=%2Fquickstart.
3. After authentication, redirect to https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}.
4. User lands in their original destination.