认证设置

面向你 Mintlify 组织的私有认证适用于所有套餐。密码认证需要 Pro 或 Enterprise 方案。OAuth 和 JWT 认证需要 Enterprise 方案。

用户必须先登录才能访问你的内容。你可以为所有页面启用完整认证，也可以启用部分认证，将部分页面设为公开、其他页面要求认证。认证仅适用于托管在自定义域名或 Mintlify 子域名上的站点。例如，docs.example.com 或 example.mintlify.site。使用自定义子路径的站点不支持认证。例如，example.com/docs。开启认证时，你可以删除现有的预览部署，否则这些预览将继续保持公开访问。请参阅开启认证时的现有预览。若要在保持页面公开的同时识别访客，请使用个性化。个性化支持自定义子路径，并且可以在访客查看页面之前无需完成认证的情况下预填 API 操作台的输入。

选择认证方式

使用下方对比表来选择适合你使用场景的认证方式。请参见功能可用性了解每种方式如何与其他 Mintlify 功能协同工作。

方式	适用场景	方案	基于用户组的访问控制	API 操作台预填	个性化
Password	简单的共享访问，无需按用户跟踪	Pro 或 Enterprise	—	—	—
Private authentication	面向 Mintlify 组织成员的内部文档	所有方案	—	—	—
OAuth 2.0	已有身份提供方或 SSO，且需要按用户会话	Enterprise	✓	✓	✓
JWT	自定义认证后端或嵌入在自有登录后的文档	Enterprise	✓	✓	✓

配置认证

密码
私有认证
OAuth 2.0
JWT（JSON Web Token）

密码认证仅提供访问控制，不支持用户级功能，例如基于用户组的访问控制或 API 操作台中的预填数据。

密码前提条件

你的安全策略允许在多个用户之间共享密码。

密码设置

创建密码。

在控制台中，前往 Access。
将 Visibility 设置为 Private。
将 Method 设置为 Password。
输入一个安全的密码。
点击 Save。

保存后，你的网站会重新部署。部署完成后，任何访问你站点的用户都必须输入该密码才能访问你的内容。

分发访问权限。

以安全方式将密码和文档 URL 分享给获授权的用户。

密码示例

你将文档托管在 docs.foo.com，只需要基础访问控制，而不需要跟踪单个用户。你希望阻止公众访问，同时保持设置简单。在控制台中创建一个强密码，并将凭证分享给获授权的用户。

私有认证前提条件

所有需要访问你站点的人都必须是你 Mintlify 组织的成员。

私有认证设置

启用私有认证。

在控制台中，前往 Access。
将 Visibility 设置为 Private。
将 Method 设置为 Authenticated。
点击 Save。

保存后，你的网站会重新部署。部署完成后，任何访问你网站的人都必须登录到你的 Mintlify 组织才能访问你的内容。

添加授权用户。

在控制台中，前往 Members。
添加所有需要访问你文档的人员。
根据他们的编辑权限分配合适的角色。

私有认证示例

你将文档托管在 docs.foo.com，并且整个团队都能访问你的控制台。你希望仅将访问权限限制在团队成员。在控制台设置中启用私有认证。通过检查所有团队成员在你的组织中是否为激活状态来验证团队访问权限。

OAuth 2.0 前提条件

支持 Authorization Code Flow (授权码流程) 的 OAuth 或 OIDC 服务器。
能够创建可通过 OAuth 访问令牌访问的 API 端点 (可选，用于启用基于用户组的访问控制) 。

OAuth 2.0 设置

配置你的 OAuth 设置。

在控制台中前往 Access。
将 Visibility 设置为 Private。
将 Method 设置为 Custom。
点击 OAuth。
配置以下字段：

Authorization URL：你的 OAuth 端点。
Client ID：你的 OAuth 2.0 客户端标识符。
Client secret：你的 OAuth 2.0 客户端密钥。
Scopes (可选) ：要请求的权限。复制 完整的 scope 字符串 (例如，对于 provider.users.docs 这样的 scope，复制完整的 provider.users.docs) 。如果需要不同的访问级别，可以使用多个 scope。
Additional authorization parameters (可选) ：要添加到初始授权请求中的其他 query 参数。
Token URL：你的 OAuth 令牌交换端点。
Info API URL (可选) ：你服务器上的一个端点，Mintlify 会调用它来获取用户信息。对于基于用户组的访问控制，请使用此字段配置 Info API 方式。你也可以改用 OAuth 令牌声明。如果两者都未配置，OAuth 流程只会验证身份。
Logout URL (可选) ：你的 OAuth 提供方自带的登出 URL。用户登出时，Mintlify 会将登出重定向与该配置的 URL 进行校验，以确保安全性。只有当重定向地址与配置的 logoutUrl 完全匹配时，重定向才会成功。如果你未配置登出 URL，用户会被重定向到 /login。Mintlify 会使用 GET 请求重定向用户，并且不会追加任何 query 参数，因此请将所有参数 (例如 returnTo) 直接包含在 URL 中。

点击 Save。

配置完 OAuth 设置后，你的网站会重新部署。部署完成后，任何访问你站点的用户都必须登录到你的 OAuth 提供方才能访问内容。

配置你的 OAuth 服务器。

从你的Access 设置中复制 Redirect URL。
将该 Redirect URL 添加为 OAuth 服务器中授权的重定向 URL。

创建用于群组访问的用户信息端点（可选）。

如要使用 Info API 方式实现基于用户组的访问控制，请创建一个 API 端点，该端点需满足：

响应 GET 请求。
接受 Authorization: Bearer <access_token> 头部用于认证。
以 User 格式返回用户数据。更多信息参见 User data format。

Mintlify 使用 OAuth 访问令牌调用此端点以获取用户信息。不会发送额外的 query 参数。将此端点 URL 填入你Access 设置中的 Info API URL 字段。

使用 OAuth 令牌声明中的用户组

如果你的身份提供方在 ID 令牌或访问令牌中包含用户组信息，你可以使用这些声明来代替 Info API URL。此选项适用于使用客户端密钥的 OAuth 配置。为项目配置 OAuth 令牌声明时，可以使用以下值：

{
  "source": "id_token",
  "groupsClaim": "groups",
  "groupsDelimiter": ","
}

source：选择 id_token 或 access_token。如果选择 id_token，请在 OAuth scopes 中包含 openid。
groupsClaim：指定包含用户组的令牌声明。默认值为 groups。
groupsDelimiter：可选的分隔符，长度为 1 至 4 个字符。Mintlify 仅使用它来拆分字符串类型的声明值。

例如，当 "groups": "general,clienta_eur" 且 groupsDelimiter 设置为 "," 时，Mintlify 会将 general 和 clienta_eur 作为两个独立的用户组。Mintlify 会删除每个用户组两侧的空格，并忽略空片段。不设置 groupsDelimiter 时，整个字符串会被视为一个用户组。数组类型的声明始终将每个字符串元素视为一个用户组，不会进行拆分。当分隔符可能出现在用户组名称中时，请不要设置 groupsDelimiter。

OAuth 2.0 示例

你将文档托管在 docs.foo.com，并且你有一个现有的 OAuth 服务器 auth.foo.com，它支持 Authorization Code Flow。在控制台中配置你的 OAuth 服务器详细信息：

Authorization URL：https://auth.foo.com/authorization
Client ID：ydybo4SD8PR73vzWWd6S0ObH
Scopes：['provider.users.docs']
Token URL：https://auth.foo.com/exchange
Info API URL：https://api.foo.com/docs/user-info
Logout URL：https://auth.foo.com/logout?returnTo=https%3A%2F%2Fdocs.foo.com

在 api.foo.com/docs/user-info 上创建一个用户信息端点，该端点要求使用带有 provider.users.docs scope 的 OAuth 访问令牌，并返回：

{
  "groups": ["engineering", "admin"],
  "expiresAt": 1893456000,
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

使用用户信息响应中的 expiresAt 字段控制会话时长。该字段为 Unix 时间戳 (自纪元以来的秒数) ，用于指示会话何时过期。更多详情请参阅用户数据格式。

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

JWT 前提条件

一个可以生成并签名 JWT 的认证系统。
一个可以创建重定向 URL 的后端服务。

JWT 设置

生成私钥。

在控制台中前往 Access。
将 Visibility 设置为 Private。
将 Method 设置为 Custom。
点击 JWT。
输入你现有登录流程的 URL。
如需提供多个登录流程，点击 Add login URL 并为每个选项填写显示名称和 URL。你最多可以配置 10 个登录 URL。
点击 Save。
点击 Generate new key。
将你的 key 安全存储在后端可以访问的位置。

生成私钥后，你的网站会重新部署。部署完成后，任何访问你网站的人都必须登录到你的 JWT 认证系统才能访问你的内容。

将 Mintlify 认证集成到你的登录流程中。

修改你现有的登录流程，在用户通过认证后增加以下步骤：

按 User 格式创建一个包含已认证用户信息的 JWT。更多信息参见 User data format。
使用 EdDSA 算法，用你的密钥对 JWT 进行签名。
创建一个返回到文档 /login/jwt-callback 路径的重定向 URL，并将 JWT 放在 URL 片段 (hash) 中。

当 JWT 认证只配置一个登录 URL 时，未认证的访客会自动重定向到该 URL。如果配置了两个或更多命名的登录 URL，访客会先看到一个选择页面，然后再进入所选的登录流程。Mintlify 会转发经过校验的 redirect 参数，使访客能够返回到他们最初请求的文档页面。

多个登录 URL 适用于完整或部分 JWT 认证。JWT 个性化只接受一个登录 URL，因为它是在不要求访客登录的前提下识别访客，同时继续向其展示公开内容。

JWT 示例

你在 docs.foo.com 上托管文档，并在 foo.com 上已有认证系统。你希望扩展登录流程，在保持文档与控制台分离的同时，为文档授予访问权限 (或者如果你没有控制台，则直接为文档授予访问权限) 。在 https://foo.com/docs-login 创建一个登录端点，用于扩展你现有的认证逻辑。在验证用户凭据之后：

按 Mintlify 的格式生成包含用户数据的 JWT。
对 JWT 进行签名并重定向到 https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}。

import * as jose from 'jose';
import { Request, Response } from 'express';

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const DOCS_HOST = 'docs.example.com';

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    host: DOCS_HOST, // 必须与你的文档 URL 匹配
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 周会话过期时间
    groups: res.locals.user.groups,
    apiPlaygroundInputs: {
      header: {
        "Authorization": `Bearer ${res.locals.user.apiKey}`,
      },
    },
  };

  const jwt = await new jose.SignJWT(user)
    .setProtectedHeader({ alg: 'EdDSA' })
    .setExpirationTime('10 s') // JWT 10 秒后过期
    .sign(signingKey);

  return res.redirect(`https://${DOCS_HOST}/login/jwt-callback#${jwt}`);
}

import jwt # pyjwt
import os

from datetime import datetime, timedelta
from fastapi.responses import RedirectResponse

private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
DOCS_HOST = 'docs.example.com'

@router.get('/auth')
async def return_mintlify_auth_status(current_user):
  jwt_token = jwt.encode(
    payload={
      'host': DOCS_HOST, # 必须与你的文档 URL 匹配
      'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()),    # JWT 10 秒后过期
      'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 周会话过期时间
      'groups': ['admin'] if current_user.is_admin else [],
      'apiPlaygroundInputs': {
        'header': {
          'Authorization': f'Bearer {current_user.api_key}',
        },
      },
    },
    key=private_key,
    algorithm='EdDSA'
  )

  return RedirectResponse(url=f'https://{DOCS_HOST}/login/jwt-callback#{jwt_token}', status_code=302)

重定向未认证用户

当未认证用户尝试访问受保护页面时，系统在重定向到你的登录 URL 时会保留用户的目标地址。

用户尝试访问受保护页面：https://docs.foo.com/quickstart。
重定向到带有 redirect 查询参数的登录 URL：https://foo.com/docs-login?redirect=%2Fquickstart。
认证完成后，重定向到 https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}。
用户将进入其最初想要访问的页面。

公开页面

在使用认证时，所有页面默认都需要通过认证才能访问。你可以在页面或分组级别通过 public 属性将特定页面设置为无需认证即可访问。

单个页面

要将页面设为公开，请在该页面的 frontmatter 中添加 public: true。

Public page example

---
title: "公开页面"
public: true
---

页面分组

要将某个分组中的所有页面设为公开，请在 docs.json 的 navigation 对象中，该分组名称下添加 "public": true。

Public group example

{
  "navigation": {
    "groups": [
      {
        "group": "公开组",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "私有组",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}

使用 groups 控制访问

当你使用 OAuth 或 JWT (JSON Web Token) 进行认证时，可以将特定页面仅限于某些用户组访问。若希望不同用户根据其角色或属性查看不同内容，这将非常有用。通过在认证过程中传递的用户数据来管理 groups。详见用户数据格式。

Example user info

{
  "groups": ["admin", "beta-users"],
  "expiresAt": 1893456000
}

使用 frontmatter 中的 groups 属性来指定哪些 groups 可以访问特定页面。

Example page restricted to the admin group

---
title: "管理员控制台"
groups: ["admin"]
---

用户必须至少属于所列的一个 groups 才能访问该页面。如果用户在不具备所需分组的情况下尝试访问页面，将会收到 404 错误。要按登录状态或分组显示或隐藏页面的部分内容，请使用 visibility 组件。可见性规则仅在浏览器中隐藏内容，因此对于敏感内容，请使用页面级 groups。

groups 如何与公共页面配合使用

默认情况下，所有页面都需要认证。
具有 groups 属性的页面仅对属于这些 groups 的已认证用户可访问。
没有 groups 属性的页面对所有已认证用户可访问。
具有 public: true 且没有 groups 属性的页面对所有人可访问。

---
title: "Public guide"
public: true
---

---
title: "API reference"
---

---
title: "Advanced configurations"
groups: ["pro", "enterprise"]
---

用户数据格式

当使用 OAuth 或 JWT 认证，或独立启用个性化时，你的系统会返回用户数据，用于控制会话时长、基于用户组成员关系的访问控制，以及内容个性化。

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

{
  "host": "docs.example.com",
  "expiresAt": 1893456000,
  "groups": ["admin", "beta-users"],
  "content": {
    "firstName": "Jane",
    "company": "Acme Corp"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    },
    "server": {
      "baseUrl": "https://api.foo.com"
    }
  }
}

string

JWT 认证时必填。 你的文档站点的主机名。该字符串必须与你部署文档的 domain 完全一致。Mintlify 会验证 JWT 的 host 是否与发起请求的 host 匹配，以防止令牌在不同站点之间被重复使用。

number

会话过期时间，以自 epoch 起算的秒数表示。当当前时间超过该值时，Mintlify 会让已存储的用户数据过期。访客必须重新完成认证或再次经过识别流程才能刷新该数据。

对于 JWT： 这不同于 JWT 的 exp 声明，后者用于决定 JWT 何时被视为无效。出于安全考虑，应将 JWT 的 exp 声明设置为较短的时长 (10 秒或更少) 。使用 expiresAt 来表示实际会话时长 (从数小时到数周) 。

string[]

用户所属用户组的列表。在使用认证时，frontmatter 中带有匹配 groups 的页面对该用户可访问。在仅启用个性化（独立于认证）时，用户组只控制页面和内容的可见性，但不会限制通过直接 URL 访问页面。示例：具有 groups: ["admin", "engineering"] 的用户可以匹配标记为 admin 或 engineering 用户组的内容。

Record<string, any>

可在 MDX 页面中通过 user 变量访问的自定义数据，用于个性化内容。

object

使用用户特定的值预填 API 操作台中的字段。当用户完成认证后，这些值会填充到 API 操作台中对应的输入字段。用户可以覆盖预填的值，其修改会持久保存在本地存储中。Mintlify 只会应用与当前端点的安全方案匹配的值。

显示 properties

Record<string, unknown>

要预填的 Header 值，以 Header 名称作为 key。

Record<string, unknown>

要预填的查询参数值，以参数名称作为 key。

要预填的 Cookie 值，以 Cookie 名称作为 key。

Record<string, string>

要预填的服务器变量值，以变量名称作为 key。

Record<string, unknown>

要预填的路径参数值，以参数名称作为 key。

功能可用性

启用认证后，部分功能的行为会有所不同，或可能不可用。

功能	公开	完全认证 (所有页面受保护)	部分认证 (部分页面公开)
llms.txt 和 llms-full.txt	完全支持	需要通过认证后才能访问，因此 AI 工具可能无法访问这些文件	可公开访问，仅反映公开页面
MCP 服务器	完全支持	连接时需要认证	公开页面无需认证即可使用，受保护页面则需要认证
Markdown 导出	完全支持	完全支持，尊重用户分组	完全支持，尊重用户分组
PDF 导出	完全支持	完全支持，尊重用户分组。已认证页面在导出时会包含图片和资源。	完全支持，尊重用户分组。已认证页面在导出时会包含图片和资源。
搜索	完全支持	完全支持，尊重用户分组	完全支持，尊重用户分组
AI 助手	完全支持	完全支持，尊重用户分组	完全支持，尊重用户分组
skill.md	完全支持	不支持	不支持
站点地图	完全支持	需要通过认证后才能访问，但会排除 groups 中的页面	需要通过认证后才能访问，但会排除 groups 中的页面
robots.txt	完全支持	需要通过认证后才能访问	需要通过认证后才能访问
实时预览	完全支持	支持编辑器自动认证	支持编辑器自动认证

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

选择认证方式

配置认证

密码前提条件

密码设置

密码示例

私有认证前提条件

私有认证设置

私有认证示例

OAuth 2.0 前提条件

OAuth 2.0 设置

使用 OAuth 令牌声明中的用户组

OAuth 2.0 示例

JWT 前提条件

JWT 设置

JWT 示例

重定向未认证用户

公开页面

单个页面

页面分组

使用 groups 控制访问

groups 如何与公共页面配合使用

用户数据格式

功能可用性

​选择认证方式

​配置认证

​密码前提条件

​密码设置

​密码示例

​私有认证前提条件

​私有认证设置

​私有认证示例

​OAuth 2.0 前提条件

​OAuth 2.0 设置

​使用 OAuth 令牌声明中的用户组

​OAuth 2.0 示例

​JWT 前提条件

​JWT 设置

​JWT 示例

​重定向未认证用户

​公开页面

​单个页面

​页面分组

​使用 groups 控制访问

​groups 如何与公共页面配合使用

​用户数据格式

​功能可用性

选择认证方式

配置认证

密码前提条件

密码设置

密码示例

私有认证前提条件

私有认证设置

私有认证示例

OAuth 2.0 前提条件

OAuth 2.0 设置

使用 OAuth 令牌声明中的用户组

OAuth 2.0 示例

JWT 前提条件

JWT 设置

JWT 示例

重定向未认证用户

公开页面

单个页面

页面分组

使用 groups 控制访问

groups 如何与公共页面配合使用

用户数据格式

功能可用性