Authentication setup

Set up user authentication to control access to pages and API references using password, OAuth, JWT, or Mintlify-managed private access.

Private authentication for your Mintlify organization is available on all plans.

Password authentication requires a Pro or Enterprise plan.

OAuth and JWT authentication require an Enterprise plan.

Authentication requires users to log in before accessing your content.

You can configure full authentication for all pages or partial authentication where some pages are public and others require authentication.

Authentication is only available for sites hosted on a custom domain or Mintlify subdomain. For example, docs.example.com or example.mintlify.site. Authentication is not supported for sites with a custom subpath. For example, example.com/docs.

Choose an authentication method

Use this comparison to pick the method that fits your use case. See Feature availability for how each method interacts with other Mintlify features.

Method	Best for	Plan	Group-based access	API playground pre-fill	Personalization
Password	Simple shared access with no per-user tracking	Pro or Enterprise	No	No	No
Private authentication	Internal site for members of your Mintlify organization	All plans	No	No	No
OAuth 2.0	Existing identity provider or SSO with per-user sessions	Enterprise	Yes	Yes	Yes
JWT	Custom auth backend or embedded content behind your own login	Enterprise	Yes	Yes	Yes

Configure authentication

Password authentication provides access control only and does not support user-specific features like group-based access control or API playground pre-filling.

Password prerequisites

Your security requirements allow sharing passwords among users.

Password setup

Create a password.

In your dashboard, go to Authentication.
In the Authentication method section, set site visibility to Private.
Click Password.
Enter a secure password.
Click Save changes.

After you save, your site redeploys. When it finishes deploying, anyone who visits your site must enter the password to access your content.

Distribute access.

Securely share the password and documentation URL with authorized users.

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

Enable private authentication.

In your dashboard, go to Authentication.
In the Authentication method section, set site visibility to Private.
Click Authenticated.
Click Save changes.

After you save, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your Mintlify organization to access your content.

Add authorized users.

In your dashboard, go to Members.
Add each person who should have access to your documentation.
Assign appropriate roles based on their editing permissions.

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

Configure your OAuth settings.

In your dashboard, go to Authentication.
In the Authentication method section, set site visibility to Private.
Click Custom.
Click OAuth.
Configure these fields:

Authorization URL: Your OAuth endpoint.
Client ID: Your OAuth 2.0 client identifier.
Client Secret: Your OAuth 2.0 client secret.
Scopes (optional): Permissions to request. Copy the entire scope string (for example, for a scope like provider.users.docs, copy the complete provider.users.docs). Use multiple scopes if you need different access levels.
Additional authorization parameters (optional): Additional query parameters to add to the initial authorization request.
Token URL: Your OAuth token exchange endpoint.
Info API URL (optional): Endpoint on your server that Mintlify calls to retrieve user info. Required for group-based access control. If omitted, the OAuth flow only verifies identity.
Logout URL (optional): The native logout URL for your OAuth provider. When users log out, Mintlify validates the logout redirect against this configured URL for security. The redirect only succeeds if it exactly matches the configured logoutUrl. If you do not configure a logout URL, users redirect to /login. Mintlify redirects users with a GET request and does not append query parameters, so include any parameters (for example, returnTo) directly in the URL.
Redirect URL (optional): The URL to redirect users to after authentication.

Click Save changes.

After you configure your OAuth settings, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your OAuth provider to access your content.

Configure your OAuth server.

Copy the Redirect URL from your authentication settings.
Add the redirect URL as an authorized redirect URL for your OAuth server.

Create your user info endpoint (optional).

To enable group-based access control, create an API endpoint that:

Responds to GET requests.
Accepts an Authorization: Bearer <access_token> header for authentication.
Returns user data in the User format. See User data format for more information.

Mintlify calls this endpoint with the OAuth access token to retrieve user information. No additional query parameters are sent.

Add this endpoint URL to the Info API URL field in your authentication settings.

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": 1735689600,
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

Control session length with the expiresAt field in your user info response. This is a Unix timestamp (seconds since epoch) indicating when the session should expire. See User data format for more details.

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

Generate a private key.

In your dashboard, go to Authentication.
In the Authentication method section, set site visibility to Private.
Click Custom.
Click JWT.
Enter the URL of your existing login flow.
Click Save changes.
Click Generate new key.
Store your key securely where your backend can access it.

After you generate a private key, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your JWT authentication system to access your content.

Integrate Mintlify authentication into your login flow.

Modify your existing login flow to include these steps after user authentication:

Create a JWT containing the authenticated user’s info in the User format. See User data format for more information.
Sign the JWT with your secret key, using the EdDSA algorithm.
Create a redirect URL back to the /login/jwt-callback path of your docs, including the JWT as the hash.

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}`);
}

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.

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

Make pages public

When using authentication, all pages require authentication to access by default. You can make specific pages viewable without authentication at the page or group level with the public property.

Individual pages

To make a page public, add public: true to the page’s frontmatter.

Public page example

---
title: "Public page"
public: true
---

Groups of pages

To make all pages in a group public, add "public": true beneath the group’s name in the navigation object of your docs.json.

Public group example

{
  "navigation": {
    "groups": [
      {
        "group": "Public group",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "Private group",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}

Control access with groups

When you use OAuth or JWT authentication, you can restrict specific pages to certain user groups. This is useful when you want different users to see different content based on their role or attributes.

Manage groups through user data passed during authentication. See User data format for details.

Example user info

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

Specify which groups can access specific pages using the groups property in frontmatter.

Example page restricted to the admin group

---
title: "Admin dashboard"
groups: ["admin"]
---

Users must belong to at least one of the listed groups to access the page. If a user tries to access a page without the required group, they’ll receive a 404 error.

How groups interact with public pages

All pages require authentication by default.
Pages with a groups property are only accessible to authenticated users in those groups.
Pages without a groups property are accessible to all authenticated users.
Pages with public: true and no groups property are accessible to everyone.

---
title: "Public guide"
public: true
---

User data format

When using OAuth or JWT authentication, your system returns user data that controls session length, group membership, and content personalization.

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

Required for JWT authentication. The hostname of your documentation site. The string must exactly match the domain where you deploy your documentation. Mintlify validates that the JWT’s host matches the requesting host to prevent token reuse across different sites.

expiresAtnumber

Session expiration time in seconds since epoch. When the current time passes this value, the user must re-authenticate.

For JWT: This differs from the JWT’s exp claim, which determines when a JWT is considered invalid. Set the JWT exp claim to a short duration (10 seconds or less) for security. Use expiresAt for the actual session length (hours to weeks).

groupsstring[]

List of groups the user belongs to. Pages with matching groups in their frontmatter are accessible to this user.

Example: A user with groups: ["admin", "engineering"] can access pages tagged with either the admin or engineering groups.

contentRecord<string, any>

Custom data accessible in MDX pages via the user variable for personalized content.

apiPlaygroundInputsobject

Pre-fills API playground fields with user-specific values. When a user authenticates, these values populate the corresponding input fields in the API playground. Users can override pre-filled values, and their overrides persist in local storage.

Mintlify applies only values that match the current endpoint’s security scheme.

Show properties

headerRecord<string, unknown>

Header values to pre-fill, keyed by header name.

queryRecord<string, unknown>

Query parameter values to pre-fill, keyed by parameter name.

cookieRecord<string, unknown>

Cookie values to pre-fill, keyed by cookie name.

serverRecord<string, string>

Server variable values to pre-fill, keyed by variable name.

pathRecord<string, unknown>

Path parameter values to pre-fill, keyed by parameter name.

Feature availability

Some features behave differently or are unavailable when you enable authentication.

Feature	Public	Fully authenticated (all pages protected)	Partially authenticated (some public pages)
llms.txt and llms-full.txt	Full support	Available behind authentication, so AI tools may not be able to access the files	Publicly accessible, reflecting public pages only
MCP server	Full support	Requires authentication to connect	Available without authentication for public pages and with authentication for protected pages
Markdown export	Full support	Full support, respects user groups	Full support, respects user groups
PDF export	Full support	Full support, respects user groups. Authenticated pages export with images and assets included.	Full support, respects user groups. Authenticated pages export with images and assets included.
Search	Full support	Full support, respects user groups	Full support, respects user groups
Assistant	Full support	Full support, respects user groups	Full support, respects user groups
skill.md	Full support	Not supported	Not supported
Sitemap	Full support	Available behind authentication, but excludes pages in groups	Available behind authentication, but excludes pages in groups
robots.txt	Full support	Available behind authentication	Available behind authentication

Authentication setup

Choose an authentication methodCopy Anchor Link

Configure authenticationCopy Anchor Link

Password prerequisitesCopy Anchor Link

Password setupCopy Anchor Link

Password exampleCopy Anchor Link

Private authentication prerequisitesCopy Anchor Link

Private authentication setupCopy Anchor Link

Private exampleCopy Anchor Link

OAuth 2.0 prerequisitesCopy Anchor Link

OAuth 2.0 setupCopy Anchor Link

OAuth 2.0 exampleCopy Anchor Link

JWT prerequisitesCopy Anchor Link

JWT setupCopy Anchor Link

JWT exampleCopy Anchor Link

Redirect unauthenticated usersCopy Anchor Link

Make pages publicCopy Anchor Link

Individual pagesCopy Anchor Link

Groups of pagesCopy Anchor Link

Control access with groupsCopy Anchor Link

How groups interact with public pagesCopy Anchor Link

User data formatCopy Anchor Link

Feature availabilityCopy Anchor Link

On this page