Authentication setup

​

Prerequisites

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

​

Implementation

​

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}.

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

​

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

​

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.

​

Prerequisites

• Your security requirements allow sharing passwords among users.

​

Implementation

​

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!