Personalized content

Customize content for identified visitors while keeping your documentation public. Examples of personalization include prefilling API keys, showing content specific to a user’s plan or role, and filtering API reference content based on group membership. Personalization uses a shared session, JWT, or OAuth to identify visitors without restricting access to your pages.

Method	Best for	Visitor identification
Shared session	Documentation and an existing application that can share a browser session	Mintlify requests user data from your Info API with the visitor’s session cookies.
JWT	An existing login flow that can sign Mintlify user data	Your login flow redirects the visitor back with a signed JWT.
OAuth	An existing OAuth 2.0 provider	Mintlify completes an OAuth flow and requests user data from your Info API.

Configure personalization

Enable personalization on the Add-ons page of your dashboard. Personalization is mutually exclusive with full authentication. JWT and OAuth authentication include personalization features.

Navigate to the Add-ons page of your dashboard.
In the Personalization section, select shared session, JWT, or OAuth.
Configure your selected personalization method.
Click Save changes.

Shared session

Shared session reuses a visitor’s existing application session, so they don’t need to log in again on your Mintlify site.

Select Shared session in the Personalization settings.
Enter an Info API URL that returns the current visitor’s user data.
Optionally enter a Login URL. Mintlify displays a login link when the Info API does not return user data.
Click Save changes.

Mintlify sends a GET request to the Info API from the visitor’s browser with credentials included. Return a successful JSON response for an identified visitor:

User data response

{
  "expiresAt": 1893456000,
  "content": {
    "firstName": "Jane",
    "plan": "Enterprise"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

For a visitor without a valid session, return a non-success response such as 401. Mintlify leaves the visitor unidentified and keeps public content available. If the Info API is on a different origin from your documentation, configure it to allow credentialed cross-origin requests from the exact documentation origin. Do not use a wildcard origin with credentials. Prevent browsers and intermediary caches from storing user data by returning Cache-Control: private, no-store.

Values in apiPlaygroundInputs are available to the browser so the API playground can send them. Return short-lived, appropriately scoped credentials, and avoid exposing a privileged application session token when a dedicated documentation token is available.

JWT and OAuth

JWT and OAuth personalization use the same user data format as shared session but don’t restrict access to your documentation. Configure these methods in Add-ons, not Authentication. For JWT personalization:

Enter the URL of your existing login flow.
Click Save changes.
Click Generate new key and store the downloaded private key securely.
In your login flow, create a JWT containing the identified visitor’s user data and sign it with the generated private key using the ES256 algorithm.
Redirect the visitor to a page on your documentation site with the signed JWT as the URL fragment. For example, https://docs.example.com/get-started#{SIGNED_JWT}. For a custom subpath, include the subpath in this URL.

Set the JWT’s exp claim to a short duration of 10 seconds or less. Use the user data expiresAt field to control how long Mintlify stores the personalization data. For OAuth personalization:

Enter your authorization URL, client ID, scopes, token URL, Info API URL, and any optional settings, then click Save changes. OAuth personalization uses the Authorization Code flow with Proof Key for Code Exchange (PKCE) and does not require a client secret.
Copy the Redirect URL from the dashboard and add it as an authorized redirect URL for your OAuth provider.
Configure the Info API to accept a GET request with the OAuth access token in the Authorization: Bearer <access_token> header and return user data.

The OAuth redirect path is /mintlify-oauth-callback. On a custom subpath, the dashboard includes the subpath in the redirect URL. Mintlify exchanges the authorization code and requests user data from the visitor’s browser. If the token or Info API endpoint is on a different origin from your documentation, configure it to allow cross-origin requests from the exact documentation origin. The Info API must allow the Authorization request header.

API key prefilling

Automatically populate API playground fields with user-specific values by returning matching field names in your user data. Include the values in the apiPlaygroundInputs field of your user data.

{
  "apiPlaygroundInputs": {
    "header": { "X-API-Key": "user_api_key_123" },
    "server": { "subdomain": "acme" }
  }
}

The field names must match the names defined in your OpenAPI specification. Mintlify applies only values that match the current endpoint’s security scheme.

Dynamic MDX content

Display content based on user information like name, plan, or organization with the user variable in your MDX pages. Include custom data in the content field of your user data.

{
  "content": {
    "firstName": "Jane",
    "company": "Acme Corp",
    "plan": "Enterprise"
  }
}

Reference these values in your MDX.

Welcome back, {user.firstName}! Your {user.plan} plan includes 100 seats for members in your {user.company} organization.

For conditional rendering based on user data, use the user variable in JSX components.

{
  user.plan === 'enterprise'
    ? <>Contact your admin to enable this feature.</>
    : <>See <a href="https://yoursite.com/pricing">pricing</a> for information about upgrading.</>
}

The user variable is an empty object for logged-out users. Use optional chaining on all user fields to prevent errors. For example, {user.org?.plan} instead of {user.org.plan}.

To read the same user object from a custom JavaScript file, use window.mintlify.user and listen for the mintlify:user event.

Page visibility

Control which pages appear in navigation based on user groups by adding groups to page frontmatter.

With personalization, groups control visibility but do not restrict access to a page. A visitor can still open a group-filtered page by navigating directly to its URL. Use authentication to restrict access to sensitive content.

---
title: "Admin settings"
groups: ["admin"]
---

OpenAPI content filtering

Filter API reference content based on user groups with the x-mint extension in your OpenAPI specification. You can filter entire endpoints, individual schema properties, oneOf variants, and enum values.

Filter endpoints

Add x-mint.groups to an operation or path to show the endpoint in navigation only to specific user groups. With standalone personalization, users not in the listed groups can still open the endpoint page by its direct URL.

{
  "paths": {
    "/billing": {
      "get": {
        "summary": "Get billing details",
        "x-mint": {
          "groups": ["admin", "billing"]
        },
        "responses": {
          "200": {
            "description": "Billing details"
          }
        }
      }
    }
  }
}

{
  "paths": {
    "x-mint": {
      "groups": ["admin", "billing"]
    },
    "/billing": {
      "get": {
        "summary": "Get billing details",
      }
    },
    "/users": {
      "get": {
        "summary": "Get user details",
      }
    }
  }
}

Filter schema properties

Add x-mint.groups to individual properties within request bodies, parameters, or responses. Properties without x-mint.groups remain visible to all users.

Restricted property

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "internal_id": {
            "type": "string",
            "x-mint": {
              "groups": ["admin"]
            }
          }
        }
      }
    }
  }
}

In this example, all users see the name property. Only users in the admin group see the internal_id property.

Filter oneOf variants

Add x-mint.groups to individual oneOf options to restrict which schema variants a user can see.

Restricted oneOf variant

{
  "schema": {
    "oneOf": [
      {
        "title": "Enterprise config",
        "type": "object",
        "x-mint": {
          "groups": ["enterprise"]
        },
        "properties": {
          "sso_enabled": { "type": "boolean" }
        }
      },
      {
        "title": "Standard config",
        "type": "object",
        "properties": {
          "notifications": { "type": "boolean" }
        }
      }
    ]
  }
}

Filter enum values

Use the x-mint-enum extension to restrict individual enum values by group. List each restricted value as a key, with its allowed groups as the value. Enum values not listed in x-mint-enum are visible to all users.

Restricted enum values

{
  "type": "string",
  "enum": ["free", "pro", "enterprise"],
  "x-mint-enum": {
    "pro": ["pro", "enterprise"],
    "enterprise": ["enterprise"]
  }
}

In this example, all users see free. Users in the pro or enterprise groups see pro. Only users in the enterprise group see enterprise.

x-mint-enum is a separate top-level extension on the schema object, not nested under x-mint.

User data format

Your identification or authentication system returns user data that controls personalization. The groups, content, and apiPlaygroundInputs fields described on this page are all part of the user data object. For the full user data format and field reference, see User data format.

Logout behavior

Logout occurs on the client side. When users click the logout button, Mintlify clears their stored session data in the browser. To limit how long personalization data persists, set the expiresAt field in your user data.

Get started

Create content

Manage your site

Agent

Assistant

Agent-ready content

Search and SEO

Document APIs

Integrations

Reference

Personalized content

Configure personalization

Shared session

JWT and OAuth

API key prefilling

Dynamic MDX content

Page visibility

OpenAPI content filtering

Filter endpoints

Filter schema properties

Filter oneOf variants

Filter enum values

User data format

Logout behavior

​Configure personalization

​Shared session

​JWT and OAuth

​API key prefilling

​Dynamic MDX content

​Page visibility

​OpenAPI content filtering

​Filter endpoints

​Filter schema properties

​Filter oneOf variants

​Filter enum values

​User data format

​Logout behavior

Configure personalization

Shared session

JWT and OAuth

API key prefilling

Dynamic MDX content

Page visibility

OpenAPI content filtering

Filter endpoints

Filter schema properties

Filter oneOf variants

Filter enum values

User data format

Logout behavior