JWT Handshake

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

​

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:

​

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:

• Original request: https://docs.foo.com/quickstart

• Redirect to login: https://foo.com/docs-login?redirect=%2Fquickstart

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}