Authentication setup

Guarantee privacy of your docs by authenticating users

Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method.

Need help choosing? See the overview to compare options.

Authentication methods are available on Growth and Enterprise plans.

Configuring authentication

Select the handshake method that you want to configure.

JWT

Prerequisites

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

Implementation

1. Generate a private key.

   1. In your dashboard, go to Authentication.
   2. Select Full Authentication or Partial Authentication.
   3. Select JWT.
   4. Enter the URL of your existing login flow and select Save changes.
   5. Select Generate new key.
   6. Store your key securely where it can be accessed by your backend.
2. 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 Sending Data 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.

Example

Your documentation is hosted 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}.

TypeScript

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

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

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

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
    groups: res.locals.user.groups,
    content: {
      firstName: res.locals.user.firstName,
      lastName: res.locals.user.lastName,
    },
  };

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

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

Redirecting unauthenticated users

When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:

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.

Prerequisites

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

Implementation

1. Generate a private key.

   1. In your dashboard, go to Authentication.
   2. Select Full Authentication or Partial Authentication.
   3. Select JWT.
   4. Enter the URL of your existing login flow and select Save changes.
   5. Select Generate new key.
   6. Store your key securely where it can be accessed by your backend.
2. 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 Sending Data 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.

Example

Your documentation is hosted 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}.

TypeScript

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

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

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

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
    groups: res.locals.user.groups,
    content: {
      firstName: res.locals.user.firstName,
      lastName: res.locals.user.lastName,
    },
  };

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

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

Redirecting unauthenticated users

When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:

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.

Prerequisites

• An OAuth server that supports the Authorization Code Flow.
• Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).

Implementation

1. Configure your OAuth settings.

   1. In your dashboard, go to Authentication.
   2. Select Full Authentication or Partial Authentication.
   3. Select OAuth and 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: Permissions to request. Use multiple scopes if you need different access levels.
   • Token URL: Your OAuth token exchange endpoint.
   • Info API URL (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty.

   4. Select Save changes.
2. Configure your OAuth server.

   1. Copy the Redirect URL from your authentication settings.
   2. Add the redirect URL as an authorized redirect URL for your OAuth server.
3. Create your user info endpoint (optional).

   To enable personalization features, create an API endpoint that:

   • Accepts OAuth access tokens for authentication.
   • Returns user data in the User format. See Sending Data for more information.

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

Example

Your documentation is hosted at foo.com/docs 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: ['docs-user-info']
• Token URL: https://auth.foo.com/exchange
• Info API URL: https://api.foo.com/docs/user-info

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

{
  "content": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "groups": ["engineering", "admin"]
}

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

Prerequisites

• Your documentation users are also your documentation editors.

Implementation

1. Enable Mintlify dashboard authentication.

   1. In your dashboard, go to Authentication.
   2. Select Full Authentication or Partial Authentication.
   3. Select Mintlify Auth.
   4. Select Enable Mintlify Auth.
2. Add authorized users.

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

Example

Your documentation is hosted at docs.foo.com and your team uses the dashboard to edit your docs. You want to restrict access to team members only.

Enable Mintlify authentication in your dashboard settings.

Verify team access by checking that all team members are added to your organization.

Password authentication provides access control only and does not support content personalization.

Prerequisites

• Your security requirements allow sharing passwords among users.

Implementation

1. Create a password.

   1. In your dashboard, go to Authentication.
   2. Select Full Authentication or Partial Authentication.
   3. Select Password.
   4. Enter a secure password.
   5. Select Save changes.
2. Distribute access.

   Securely share the password and documentation URL with authorized users.

Example

Your documentation is hosted 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. That’s it!

Assistant

Responses are generated using AI and may contain mistakes.