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.