Personalization setup

Let users log in for customized documentation experiences

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

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

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

Prerequisites

• An OAuth server that supports the Auth Code with PKCE Flow.
• Ability to create an API endpoint accessible by OAuth access tokens.

Implementation

1. Create user info API endpoint.

   Create an API endpoint that:

   • Accepts OAuth access tokens for authentication.
   • Returns user data in the User format. See Sending Data for more information.
   • Defines the scopes for access.
2. Configure your OAuth personalization settings.

   1. In your dashboard, go to Authentication.
   2. Select Personalization.
   3. Select OAuth and configure these fields:

   • Authorization URL: Your OAuth authorization endpoint.
   • Client ID: Your OAuth 2.0 client identifier.
   • Scopes: Permissions to request. Must match the scopes of the endpoint that you configured in the first step.
   • Token URL: Your OAuth token exchange endpoint.
   • Info API URL: Endpoint to retrieve user data for personalization. Created in the first step.

   4. Select Save changes
3. Configure your OAuth server.

   1. Copy the Redirect URL from your authentication settings.
   2. Add this URL as an authorized redirect URL in your OAuth server configuration.

Example

Your documentation is hosted at foo.com/docs and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.

Create a user info endpoint at api.foo.com/docs/user-info, which requires an OAuth access token with the docs-user-info scope and responds with the user’s custom data:

{
  "content": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "groups": ["engineering", "admin"]
}

Configure your OAuth server details in your dashboard:

• Authorization URL: https://auth.foo.com/authorization
• Client ID: ydybo4SD8PR73vzWWd6S0ObH
• Scopes: ['docs-user-info']
• Token URL: https://auth.foo.com/exchange
• Info API URL: https://api.foo.com/docs/user-info

Configure your OAuth server to allow redirects to your callback URL.

Prerequisites

• A dashboard or user portal with cookie-based session authentication.
• Ability to create an API endpoint at the same origin or subdomain as your dashboard.
  • If your dashboard is at foo.com, the API URL must start with foo.com or *.foo.com.
  • If your dashboard is at dash.foo.com, the API URL must start with dash.foo.com or *.dash.foo.com.
• Your docs are hosted at the same domain or subdomain as your dashboard.
  • If your dashboard is at foo.com, your docs must be hosted at foo.com or *.foo.com.
  • If your dashboard is at *.foo.com, your docs must be hosted at foo.com or *.foo.com.

Implementation

1. Create user info API endpoint.

   Create an API endpoint that:

   • Uses your existing session authentication to identify users
   • Returns user data in the User format (see Sending Data)
   • If the API domain and the docs domain do not exactly match:
     • Add the docs domain to your API’s Access-Control-Allow-Origin header (must not be *).
     • Set your API’s Access-Control-Allow-Credentials header to true.
     Only enable CORS headers on this specific endpoint, not your entire dashboard API.

2. Configure your personalization settings

   1. In your dashboard, go to Authentication.
   2. Select Personalization.
   3. Select Shared Session.
   4. Enter your Info API URL, which is the endpoint from the first step.
   5. Enter your Login URL, where users log into your dashboard.
   6. Select Save changes.

Examples

Dashboard at subdomain, docs at subdomain

You have a dashboard at dash.foo.com, which uses cookie-based session authentication. Your dashboard API routes are hosted at dash.foo.com/api. You want to set up personalization for your docs hosted at docs.foo.com.

Setup process:

1. Create endpoint dash.foo.com/api/docs/user-info that identifies users via session authentication and responds with their user data.
2. Add CORS headers for this route only:
   • Access-Control-Allow-Origin: https://docs.foo.com
   • Access-Control-Allow-Credentials: true
3. Configure API URL in authentication settings: https://dash.foo.com/api/docs/user-info.

Dashboard at subdomain, docs at root

You have a dashboard at dash.foo.com, which uses cookie-based session authentication. Your dashboard API routes are hosted at dash.foo.com/api. You want to set up personalization for your docs hosted at foo.com/docs.

Setup process:

1. Create endpoint dash.foo.com/api/docs/user-info that identifies users via session authentication and responds with their user data.
2. Add CORS headers for this route only:
   • Access-Control-Allow-Origin: https://foo.com
   • Access-Control-Allow-Credentials: true
3. Configure API URL in authentication settings: https://dash.foo.com/api/docs/user-info.

Dashboard at root, docs at root

You have a dashboard at foo.com/dashboard, which uses cookie-based session authentication. Your dashboard API routes are hosted at foo.com/api. You want to set up personalization for your docs hosted at foo.com/docs.

Setup process:

1. Create endpoint foo.com/api/docs/user-info that identifies users via session authentication and responds with their user data.
2. Configure API URL in authentication settings: https://foo.com/api/docs/user-info

No CORS configuration is needed since the dashboard and docs share the same domain.

Assistant

Responses are generated using AI and may contain mistakes.