个性化设置

让用户登录以获得个性化的文档体验

当用户登录后，个性化会为其量身定制你的文档。例如，你可以预填其 API 密钥，展示与其套餐或角色相关的内容，或隐藏其无需访问的部分。

​

个性化功能

使用以下个性化能力来自定义内容。

​

API 密钥预填

通过在用户数据中返回与字段名称相同的键，自动为 API交互测试台 的字段填入用户特定的值。要实现自动预填，用户数据中的字段名必须与 API交互测试台 中的字段名称完全一致。

​

动态 MDX 内容

使用 user 变量，根据用户信息（如姓名、套餐或组织）展示动态内容。

欢迎回来，{user.firstName}！你的 {user.org?.plan} 方案包含……

查看下方用户数据格式部分，了解详细示例和实现指南。

​

页面可见性

在页面的 frontmatter 中添加 groups 字段，以限制哪些页面对你的用户可见。默认情况下，每个页面对所有用户可见。

用户只会看到其所属 groups 中的页面。

---
title: "管理你的用户"
description: "在你的组织中添加和移除用户"
groups: ["admin"]
---

​

用户数据格式

在实现个性化时，系统会以特定格式返回用户数据，以支持内容定制。根据握手方式不同，这些数据可以作为原始 JSON 对象发送，或封装在已签名的 JWT 中。两种方式的数据结构一致。

type User = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};

expiresAt · number

会话过期时间，单位为自 Unix 纪元以来的秒数。如果用户在此时间之后加载页面，其存储的数据将被自动删除，并且必须重新认证。

groups · string[]

用户所属的分组列表。其 frontmatter 中带有匹配 groups 的页面对该用户可见。

示例：具有 groups: ["admin", "engineering"] 的用户可以访问带有 admin 或 engineering 分组标签的页面。

content · object

可通过 user 变量在你的 MDX 内容中访问的自定义数据。用于在整个文档中实现动态个性化。

基础示例：

{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }

在 MDX 中的用法：

Welcome back, {user.firstName}! Your {user.plan} plan includes...

使用示例 user 数据时，将渲染为：Welcome back, Ronan! Your Enterprise plan includes…

高级条件渲染：

Authentication is an enterprise feature. {
  user.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : user.org.plan !== 'enterprise'
      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
      : <>To request this feature for your enterprise org, contact your admin.</>
}

user 中的信息仅对已登录用户可用。对于未登录用户，user 的值为 {}。为防止页面在未登录情况下崩溃，请始终在 user 字段上使用可选链。例如，{user.org?.plan}。

apiPlaygroundInputs · object

用于预填 API 交互测试台字段的用户特定值。在测试 API 时，通过自动填充数据为用户节省时间。

示例：

{
  "header": { "X-API-Key": "user_api_key_123" },
  "server": { "subdomain": "foo" },
  "query": { "org_id": "12345" }
}

如果某个用户在特定子域发起请求，你可以将 { server: { subdomain: 'foo' } } 作为 apiPlaygroundInputs 字段发送。该值会在任何包含 subdomain 字段的 API 页面上被预填。

仅当 header、query 和 cookie 字段属于你的 OpenAPI security scheme 时才会预填。如果某个字段位于 Authorization 或 Server 部分，它将被预填。创建一个名为 Authorization 的标准 Header 参数并不会启用此功能。

​

示例用户数据

{
  "expiresAt": 1735689600,
  "groups": ["admin", "beta-users"],
  "content": {
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "plan": "Enterprise",
    "region": "us-west"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer abc123",
      "X-Org-ID": "techcorp"
    },
    "server": {
      "environment": "production",
      "region": "us-west"
    }
  }
}

​

配置个性化

选择要配置的握手机制。

JWT

​

先决条件

• 一个能够生成并签署 JWT 的登录系统
• 一个能够创建重定向 URL 的后端服务

​

实施

1. 生成私钥。

   1. 在你的控制台中，前往 Authentication。
   2. 选择 Personalization（个性化）。
   3. 选择 JWT。
   4. 输入你现有登录流程的 URL，并选择 Save changes（保存更改）。
   5. 选择 Generate new key（生成新密钥）。
   6. 将密钥安全存放在后端可访问的位置。
2. 将 Mintlify 个性化集成到你的登录流程中。

   在用户登录后，修改你现有的登录流程以包含以下步骤：

   • 使用 User 格式创建一个包含已登录用户信息的 JWT。有关更多信息，请参见上方的 User data format 部分。
   • 使用 ES256 算法与该私钥对 JWT 进行签名。
   • 创建一个返回到文档站点的重定向 URL，并将 JWT 作为哈希附加其后。

​

示例

你的文档托管在 docs.foo.com。你希望文档与控制台分离（或你没有控制台）并启用个性化。

先生成一个 JWT 密钥。然后在 https://foo.com/docs-login 创建一个登录端点，以启动到文档的登录流程。

在验证用户凭据之后：

• 以 Mintlify 的格式生成包含用户数据的 JWT。
• 对 JWT 进行签名并重定向到 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}`);
}

​

保留页面锚点

若要在登录后将用户重定向到特定小节，请使用以下 URL 格式：https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}。

示例：

• 原始 URL：https://docs.foo.com/quickstart#step-one
• 重定向后的 URL：https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one

OAuth 2.0

​

先决条件

• 支持带 PKCE 的授权码流程（Auth Code with PKCE Flow）的 OAuth 服务器
• 能创建可由 OAuth 访问令牌访问的 API 端点

​

实施

1. Create user info API endpoint.

   创建一个 API 端点，该端点：

   • 接收 OAuth 访问令牌进行认证。
   • 按 User 格式返回用户数据。详见上方的用户数据格式。
   • 定义访问所需的 scope。
2. Configure your OAuth personalization settings.

   1. 在控制台中前往 Authentication。
   2. 选择 Personalization。
   3. 选择 OAuth 并配置以下字段：

   • Authorization URL：OAuth 授权端点。
   • Client ID：OAuth 2.0 客户端标识符。
   • Scopes：请求的权限。请复制完整的 scope 字符串（例如，scope 为 provider.users.docs 时，复制完整的 provider.users.docs）。必须与第一步中配置的端点 scopes 匹配。
   • Token URL：OAuth 令牌交换端点。
   • Info API URL：用于获取个性化所需用户数据的端点（在第一步创建）。

   4. 选择 Save changes
3. Configure your OAuth server.

   1. 从身份验证设置中复制 Redirect URL。
   2. 将此 URL 添加为 OAuth 服务器配置中的已授权重定向 URL。

​

示例

你的文档托管在 foo.com/docs，并且已有一个支持 PKCE 流程的 OAuth 服务器。你希望基于用户数据对文档进行个性化。

在 api.foo.com/docs/user-info 创建用户信息端点，该端点需要携带具有 provider.users.docs scope 的 OAuth 访问令牌，并返回用户的自定义数据：

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

在控制台中配置 OAuth 服务器的详细信息：

• 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

将 OAuth 服务器配置为允许重定向到你的回调 URL。

共享会话

​

前置条件

• 具备采用基于 Cookie 的会话认证的控制台或用户门户。
• 能在与控制台相同的源或子域上创建一个 API 端点。
  • 如果你的控制台在 foo.com，则 API URL 必须以 foo.com 或 *.foo.com 开头。
  • 如果你的控制台在 dash.foo.com，则 API URL 必须以 dash.foo.com 或 *.dash.foo.com 开头。
• 你的文档与控制台托管在相同的域或子域上。
  • 如果你的控制台在 foo.com，你的 文档 必须托管在 foo.com 或 *.foo.com。
  • 如果你的控制台在 *.foo.com，你的 文档 必须托管在 foo.com 或 *.foo.com。

​

实施

1. 创建用户信息 API 端点。

   创建一个 API 端点，该端点：

   • 使用你现有的会话认证来识别用户

   • 以 User 格式返回用户数据（参见上面的 User data format 部分）

   • 如果 API 域与文档域不完全匹配：

     • 将文档域添加到 API 的 Access-Control-Allow-Origin 响应头中（不能为 *）。
     • 将 API 的 Access-Control-Allow-Credentials 响应头设置为 true。
     仅在此特定端点上启用 CORS 响应头，而不要对整个控制台 API 启用。

2. 配置你的个性化设置

   1. 在你的控制台中，前往 Authentication。
   2. 选择 Personalization。
   3. 选择 Shared Session。
   4. 输入你的 Info API URL，即第一步中的端点。
   5. 输入你的 Login URL，即用户登录你控制台的地址。
   6. 选择 Save changes。

​

示例

​

控制台在子域，文档在子域

你在 dash.foo.com 有一个控制台，使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 dash.foo.com/api。你希望为托管在 docs.foo.com 的文档设置个性化。

设置流程：

1. 创建端点 dash.foo.com/api/docs/user-info，通过会话认证识别用户并返回其用户数据。
2. 仅为该路由添加 CORS 响应头：
   • Access-Control-Allow-Origin: https://docs.foo.com
   • Access-Control-Allow-Credentials: true
3. 在认证设置中配置 API URL：https://dash.foo.com/api/docs/user-info。

​

控制台在子域，文档在根域

你在 dash.foo.com 有一个控制台，使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 dash.foo.com/api。你希望为托管在 foo.com/docs 的文档设置个性化。

设置流程：

1. 创建端点 dash.foo.com/api/docs/user-info，通过会话认证识别用户并返回其用户数据。
2. 仅为该路由添加 CORS 响应头：
   • Access-Control-Allow-Origin: https://foo.com
   • Access-Control-Allow-Credentials: true
3. 在认证设置中配置 API URL：https://dash.foo.com/api/docs/user-info。

​

控制台在根域，文档在根域

你在 foo.com/dashboard 有一个控制台，使用基于 Cookie 的会话认证。你的控制台 API 路由托管在 foo.com/api。你希望为托管在 foo.com/docs 的文档设置个性化。

设置流程：

1. 创建端点 foo.com/api/docs/user-info，通过会话认证识别用户并返回其用户数据。
2. 在认证设置中配置 API URL：https://foo.com/api/docs/user-info

无需进行 CORS 配置，因为控制台与文档使用相同的域名。