跳转到主要内容
当用户登录后，个性化功能会为每位用户定制你的文档。例如，你可以预填他们的 API key，展示与其套餐或角色相关的内容，或隐藏他们无权访问的部分。

​
个性化功能

使用以下个性化能力定制内容。

​
API key 预填

通过在用户数据中返回与字段名称一致的项，自动为 API 操作台的字段填入用户特定的值。要使自动预填生效，用户数据中的字段名称必须与 API 操作台中的名称完全一致。

​
动态 MDX 内容

使用 user 变量，根据用户信息（如姓名、方案或组织）显示动态内容。 
欢迎回来，{user.firstName}！您的 {user.org?.plan} 套餐包含...
请参阅下方的用户数据格式部分，获取详细示例和实现指南。

​
页面可见性

通过在页面的 frontmatter 中添加 groups 字段来限制哪些页面对您的用户可见。默认情况下，所有用户都能看到所有页面。 用户只会看到其所属 groups 中的页面。 
---
title: "管理您的用户"
description: "在您的组织中添加和删除用户"
groups: ["admin"]
---

​
用户数据格式

在实现个性化时，系统会以特定格式返回用户数据，以便进行内容定制。根据握手方式的不同，这些数据可以作为原始 JSON 对象发送，或封装在已签名的 JWT（JSON Web Token）中。两种方式的数据结构相同。 
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 纪元起计算的秒数表示。如果用户在该时间之后加载页面，其存储的数据会被自动删除，并且必须重新进行认证。
关于 JWT 握手： 这与 JWT 的 exp 声明不同，后者决定 JWT 何时被视为无效。出于安全考虑，将 JWT 的 exp 声明设置为较短的时长（10 秒或更短）。使用 expiresAt 表示实际的会话时长（从数小时到数周）。
​
groups
string[]
用户所属的 groups 列表。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 安全方案时才会预填。如果字段位于 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（JSON Web Token）
  • OAuth 2.0
  • 共享会话

​
先决条件

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

​
实施

1

生成私钥。

  1. 在你的控制台，前往 认证。
  2. 选择 Personalization。
  3. 选择 JWT。
  4. 输入你现有登录流程的 URL，并选择 保存更改。
  5. 选择 Generate new key。
  6. 将你的 key 安全存放在后端可访问的位置。
2

将 Mintlify 个性化集成到你的登录流程中。

在用户登录后，修改你现有的登录流程以包含以下步骤：
  • 按 User 格式创建一个包含已登录用户信息的 JWT。更多信息参见上方的用户数据格式。
  • 使用 ES256 算法和密钥对该 JWT 进行签名。
  • 创建一个返回到你的文档站点的重定向 URL，并将 JWT 作为 hash 包含其中。

​
示例

你的文档托管在 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
⌘I