当用户登录后，个性化会为每位用户定制你的文档。例如，你可以预填他们的 API key，显示与其套餐或角色相关的内容，或隐藏他们不需要的部分。
使用以下个性化功能定制内容。
通过在用户数据中返回与字段同名的属性，可将用户特定的值自动填入 API 操作台的对应字段。要使自动预填充生效，用户数据中的字段名称必须与 API 操作台中的字段名称完全一致。
使用 user 变量，根据用户信息（如姓名、订阅计划或组织）展示动态内容。
欢迎回来，{user.firstName}！您的 {user.org?.plan} 套餐包含...
groups 字段，可限制哪些页面对你的用户可见。默认情况下，所有用户都能看到所有页面。
用户只会看到其所属 groups 下的页面。
---
title: "管理您的用户"
description: "在您的组织中添加和删除用户"
groups: ["admin"]
---
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>;
};
};
会话过期时间，以 自 Unix epoch 起经过的秒数 表示。如果用户在该时间之后加载页面，其已存储的数据会被自动删除，并且必须重新进行认证。
对于 JWT 握手：这与 JWT 的 exp 声明不同，exp 决定的是 JWT 何时被视为无效。出于安全考虑，请将 JWT 的 exp 声明设置为较短的有效期（10 秒或更少）。使用 expiresAt 来控制实际的会话时长（从数小时到数周）。
用户所属的用户组列表。frontmatter 中 groups 值匹配的页面对该用户可见。示例：具有 groups: ["admin", "engineering"] 的用户，可以访问在 groups 中标记为 admin 或 engineering 的页面。
可通过 user 变量在 MDX 内容中访问的自定义数据。使用它为整个文档提供动态个性化体验。基础示例：{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
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}。
用于预填 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（JSON Web Token）
OAuth 2.0
共享会话
先决条件
- 一个能够生成并签署 JWT 的登录系统
- 一个能够创建重定向 URL 的后端服务
生成私钥。
- 在控制台前往 认证。
- 选择 Personalization。
- 选择 JWT。
- 输入你现有登录流程的 URL，并选择 保存更改。
- 选择 Generate new key。
- 将你的 key 安全存储在后端可访问的位置。
将 Mintlify 个性化集成到你的登录流程。
在用户登录后，修改你现有的登录流程以包含以下步骤：
- 生成一个包含已登录用户信息、符合
User 格式的 JWT。更多信息请参见上面的 User data format 部分。
- 使用 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
