JWT Handshake

Use a customized login flow to authenticate users

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 Mintlify 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 Mintlify 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 Mintlify dashboard settings and enter https://foo.com/docs-login for the Login URL field.

Here’s what the code might look like:

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