Skip to main content
This is the documentation for the JWT Authentication Handshake. The steps for setting up the JWT Personalization Handshake are slightly different.
If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.

​
Implementation

1

Generate a private key

Go to your dashboard settings and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
2

Create a login flow

Create a login flow that does the following:
  • Authenticate the user
  • Create a JWT containing the authenticated user’s info in the User format
  • Sign the JWT with the 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
3

Configure your Authentication settings

Return to your dashboard settings and add the login URL to your Authentication settings.

​
Example

I want to set up authentication for my docs hosted at docs.foo.com. I want my docs to be completely separate from my dashboard (or I don’t have a dashboard at all). To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL https://foo.com/docs-login that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, I create a JWT containing the user’s custom data according to Mintlify’s specification. I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the form https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}, and redirect the user. I then go to the dashboard settings and enter https://foo.com/docs-login for the Login URL field. Here’s what the code might look like: 
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 specific page, Mintlify preserves their intended destination through a redirect flow:
  1. The user attempts to visit a certain page (e.g., /quickstart)
  2. Mintlify redirects them to your login URL and adds the (relative) original destination as a redirect query parameter
Example: After successful authentication, you can include this same redirect parameter in your JWT callback URL to send users to their intended destination: https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}
⌘I