Skip to main content
Personalization lets you customize your documentation based on user information. This guide covers setup for each available handshake method. Need help choosing? See the overview to compare options.

​
Configuring personalization

Select the handshake method that you want to configure.
  • JWT
  • OAuth 2.0
  • Shared session

​
Prerequisites

  • A login 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 Personalization.
  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 personalization into your login flow.

Modify your existing login flow to include these steps after user login:
  • Create a JWT containing the logged in user’s info in the User format. See Sending Data for more information.
  • Sign the JWT with the secret key, using the ES256 algorithm.
  • Create a redirect URL back to your docs, including the JWT as the hash.

​
Example

Your documentation is hosted at docs.foo.com. You want your docs to be separate from your dashboard (or you don’t have a dashboard) and enable personalization.Generate a JWT secret. Then create a login endpoint at https://foo.com/docs-login that initiates a login flow to your documentation.After verifying user credentials:
  • Generate a JWT with user data in Mintlify’s format.
  • Sign the JWT and redirect to https://docs.foo.com#{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, 'ES256');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
    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: 'ES256' })
    .setExpirationTime('10 s')
    .sign(signingKey);

  return res.redirect(`https://docs.foo.com#${jwt}`);
}

​
Preserving page anchors

To redirect users to specific sections after login, use this URL format: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}.Example:
  • Original URL: https://docs.foo.com/quickstart#step-one
  • Redirect URL: https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one
⌘I