Personalization setup

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.

Prerequisites

A login system that can generate and sign JWTs.
A backend service that can create redirect URLs.

Implementation

Generate a private key.

In your dashboard, go to Authentication.
Select Personalization.
Select JWT.
Enter the URL of your existing login flow and select Save changes.
Select Generate new key.
Store your key securely where it can be accessed by your backend.

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

Generate a private key.

In your dashboard, go to Authentication.
Select Personalization.
Select JWT.
Enter the URL of your existing login flow and select Save changes.
Select Generate new key.
Store your key securely where it can be accessed by your backend.

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

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.

Configure your OAuth personalization settings.

In your dashboard, go to Authentication.
Select Personalization.
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.

Select Save changes

Configure your OAuth server.

Copy the Redirect URL from your authentication settings.
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

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.

Configure your personalization settings

In your dashboard, go to Authentication.
Select Personalization.
Select Shared Session.
Enter your Info API URL, which is the endpoint from the first step.
Enter your Login URL, where users log into your dashboard.
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:

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

Dashboard at subdomain, docs at root

Setup process:

Create endpoint dash.foo.com/api/docs/user-info that identifies users via session authentication and responds with their user data.
Add CORS headers for this route only:
- Access-Control-Allow-Origin: https://foo.com
- Access-Control-Allow-Credentials: true
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:

Create endpoint foo.com/api/docs/user-info that identifies users via session authentication and responds with their user data.
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.

Getting started

Core configuration

Components

API pages

Authentication and personalization

Guides

Integrations

Version control and CI/CD

Personalization setup

Configuring personalization

Prerequisites

Implementation

Example

Preserving page anchors

Prerequisites

Implementation

Example

Preserving page anchors

Prerequisites

Implementation

Example

Prerequisites

Implementation

Examples

Dashboard at subdomain, docs at subdomain

Dashboard at subdomain, docs at root

Dashboard at root, docs at root

Getting started

Core configuration

Components

API pages

Authentication and personalization

Guides

Integrations

Version control and CI/CD

​Configuring personalization

​Prerequisites

​Implementation

​Example

​Preserving page anchors

​Prerequisites

​Implementation

​Example

​Preserving page anchors

​Prerequisites

​Implementation

​Example

​Prerequisites

​Implementation

​Examples

​Dashboard at subdomain, docs at subdomain

​Dashboard at subdomain, docs at root

​Dashboard at root, docs at root

Configuring personalization

Prerequisites

Implementation

Example

Preserving page anchors

Prerequisites

Implementation

Example

Preserving page anchors

Prerequisites

Implementation

Example

Prerequisites

Implementation

Examples

Dashboard at subdomain, docs at subdomain

Dashboard at subdomain, docs at root

Dashboard at root, docs at root