Skip to main content

Personalization requires authentication configured with OAuth or JWT.

Customize content for your users when they log in to your documentation site. You can prefill API keys, show content specific to a user's plan or role, and filter API reference content based on group membership.

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. Only values that match the current endpoint's security scheme are applied.

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}.

Page visibility

Restrict pages to specific user groups by adding groups to page frontmatter. Users must belong to at least one listed group to access the page.

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

For more details on how groups interact with public pages, see Control access with groups.

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 restrict the endpoint page to specific user groups. Users not in the listed groups won't see the endpoint in navigation or be able to access its page.

{ "paths": { "/billing": { "get": { "summary": "Get billing details", "x-mint": { "groups": ["admin", "billing"] }, "responses": { "200": { "description": "Billing 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.

{11-13} 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.

{7-9} 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.

{4-7} 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 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, Docfiy clears their stored session data in the browser.

To limit how long personalization data persists, set the expiresAt field in your user data.