如何在 Mintlify 中配置私有 API 文档的门禁访问与用户身份认证

对于维护面向付费合作伙伴、企业采购客户或生态集成商的技术团队与平台架构师而言，私有 API 文档常常陷入两难抉择：一方面，团队希望利用 Mintlify 现代化的 MDX 与 OpenAPI 引擎构建极富表现力的交互式 API 参考和在线调试 Playground；另一方面，核心结算接口、内部管理端点及专有 SDK 又必须受到严格隔离，严防公开爬虫抓取和未授权访问。

Mintlify 通过统一的访问控制架构解决了这一痛点，支持四类认证模式：Mintlify 组织成员内部访问、全局密码保护、企业级单点登录（SSO / OAuth 2.0）以及自定义 JWT（JSON Web Token）令牌校验。本文将深入解析私有文档的域名限制、配置工作流、页面级分组分权策略以及交互式 Playground 的安全凭证预填方案，指导工程团队快速落地生产级受限访问体系。

核心架构前提与域名约束

在进入具体配置前，工程团队必须明确 Mintlify 处理门禁访问的关键边界：

1. 独立域名托管约束： 无论是全局认证还是局部认证，Mintlify 均要求文档必须部署在独立自定义域名（例如 docs.api.example.com）或 Mintlify 二级子域名（如 example.mintlify.site）。基于子路径的部署（例如 example.com/docs）不支持门禁认证机制。若业务架构受限于子路径部署，只能采用无强制拦截的客户端个性化方案。
2. 访问隔离粒度（全局 vs. 局部）： 团队可在后台按需选择全局认证（Full Authentication）（整站所有页面与 OpenAPI 规范必须登录后访问）或局部认证（Partial Authentication）（公共快速入门与开放端点对外公开，仅对核心商业接口与私有模块施加登录拦截）。
3. PR 预览部署（Preview Deployments）安全： 团队通过 Git 集成自动触发文档更新时，未受保护的 Pull Request 预览链接极易导致未发布端点泄漏。在 Mintlify 后台开启认证体系后，所有预览分支均会自动继承安全门禁。

认证方案对比矩阵

方案一：全局密码保护（极简轻量门禁）

如果当前处于向少数核心客户提供 SDK 早期内测或受保密协议保护的阶段，密码保护可在无需对接任何身份提供商的情况下实现即时拦截。

配置工作流

1. 登录 Mintlify 控制台，进入对应项目的 Access（访问控制）面板。
2. 将 Visibility（可见性）从 Public 改为 Private。
3. 将认证方式 Method 选为 Password。
4. 输入具备足够强度的共享密码，点击 Save changes 保存生效。

权衡与工程考量

该方案部署耗时不足两分钟，但由于所有访问者共享同一个凭据，系统无法追踪单一用户的阅读审计日志，无法针对不同角色开放差异化接口，且当某位离职人员或外部测试方离开时，必须更改全站密码。因此，密码保护仅推荐用于过渡期或演示环境。

方案二：企业单点登录与 OAuth 2.0（身份联合接入）

对于面向企业员工内部使用或与重点商业客户建立身份联合的场景，通过 SAML 2.0 或 OAuth 2.0 对接企业身份提供商（IdP），不仅符合安全合规要求，还能保证员工离职后自动注销文档访问权。

Okta SAML 2.0 标准配置步骤

1. 获取 Mintlify 终端信息： 在 Mintlify 后台导航至 Security 页面，点击 Configure 并选择 Okta SAML。复制系统生成的 Single sign on URL（ACS 地址）与 Audience URI（实体 ID）。
2. 在 IdP 端创建 SAML 应用： 进入 Okta 管理控制台，选择 Applications > Create App Integration > SAML 2.0，将第一步复制的 URL 与 URI 填入相应字段。
3. 映射用户属性字段： 按照 Mintlify 规范配置声明属性：
   • firstName 映射至 user.firstName；
   • lastName 映射至 user.lastName；
   • Name 映射至 user.email，且 Name ID 格式指定为 EmailAddress。
4. 回填元数据完成绑定： 从 Okta 复制 Metadata URL（元数据链接），粘贴回 Mintlify 的 Metadata 配置项中，点击 Save changes 保存。

配置生效后，外部请求访问文档站点时将自动重定向至企业 IdP 认证网关，鉴权通过后方可加载私有 API 规格与文档内容。

方案三：基于 JWT 的自定义身份认证（主站无缝对接）

在商业 SaaS 或现代化开发者平台中，集成商通常已在您的主站控制台（Console）完成登录。为避免开发者查阅私有 API 时经历二次登录，Mintlify 提供了基于非对称签名的 JWT 鉴权桥接机制。

架构交互时序

开发者浏览器                   业务系统主站后端                   Mintlify 文档站点
     |                                |                                   |
     | 1. 在主站点击「私有 API 参考」    |                                   |
     |------------------------------->|                                   |
     |                                | 2. 注入用户信息与角色权限，         |
     |                                |    使用 ES256 私钥签署 JWT 令牌    |
     | 3. 重定向至文档站点 URL Hash   |                                   |
     |    https://docs.example.com/#JWT|                                  |
     |<-------------------------------|                                   |
     |                                                                    |
     | 4. 携带 URL Hash 中的 JWT 请求文档页面                             |
     |------------------------------------------------------------------->|
     |                                | 5. 校验 ES256 签名有效性，        |
     |                                |    提取 groups 角色，并清除 Hash  |
     | 6. 渲染受限私有接口与预填充的 Playground                           |
     |<-------------------------------------------------------------------|

实施步骤

1. 登录 Mintlify 控制台，进入 Access 或 Personalization 设置，选择 JWT 认证方式，并填入主站登录重定向地址。
2. 在控制台生成公私钥对，安全保管由 Mintlify 分配的私钥（建议保存在服务端 Secrets Manager 或 KMS 中）。
3. 服务端在处理跳转请求时，生成包含用户信息、会话有效期及 API 分组权限的 Payload，并采用 ES256 算法完成签名：

import jwt from "jsonwebtoken";

// Node.js 服务端生成 Mintlify 门禁 Token 示例
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // 标准 JWT 声明
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // 短暂过期时间：10秒以内
    
    // Mintlify 专属会话有效期字段
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8小时本地会话
    
    // 供 MDX 条件渲染调用的上下文数据
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // 例如 "enterprise" 或 "fintech-vip"
    },
    
    // 用于导航与页面访问拦截的分组权限列表
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // 用于自动预填 API Playground 的凭证
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. 将前端重定向到文档站点时，将生成的 JWT 放在 URL Fragment（Hash 锚点）中：

   https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   Mintlify 前端加载后会自动解析 URL Hash 中的签名数据，利用注册的公钥完成校验并建立本地受限会话，随后立即通过浏览器 History API 抹除该 Hash，防止令牌在浏览器历史记录或 HTTP Referer 中残留泄露。

页面级分组分权（RBAC）与精细化内容隔离

完成身份认证后，平台工程团队往往需要针对不同等级的合作伙伴实施文档分权隔离。

1. MDX Frontmatter 页面级门禁

在敏感端点对应的 .mdx 文件头部声明 groups 标签：

---
title: "核心清结算 Webhooks"
description: "专为大客户结算平台提供的高并发支付回调规范"
groups: ["enterprise", "fintech-partners"]
---

若当前会话的 JWT 或 SSO 属性中未包含所要求的权限分组，Mintlify 会在侧边栏导航中彻底隐藏该文档，并在直接通过 URL 访问时返回访问受限（404 或拦截状态），杜绝内部 API 暴露。

2. MDX 内部基于 userContext 的动态分支渲染

若通用指南页面中仅包含部分私密说明，可直接借助 userContext 实现按身份动态展现：

# 平台调用频次与限流规则

{userContext?.content?.plan === "enterprise" ? (
  <Card title="专属大客通道" icon="shield-check">
    您的企业享受专属 10,000 QPS 带宽配额与 7x24 小时技术支持保障。
  </Card>
) : (
  <Card title="标准限流阈值" icon="gauge">
    标准开发者限流上限为 200 QPM。如需开通专有流水接口，请联系商务团队。
  </Card>
)}

3. 人类用户与 AI Agent 的内容分流防爬

Mintlify 默认会将站点内容转换为 Markdown 格式供 LLM 与 AI 编码工具读取。如果某些私密内部逻辑不希望被爬虫或外部 Agent 抽取，可使用 <Visibility> 组件进行隔离：

<Visibility for="humans">
  <Note>生产环境密钥必须每 90 天在客户控制台手动发起一次滚动更新。</Note>
</Visibility>

<Visibility for="agents">
  API 请求须在 Authorization 请求头中附带 Bearer 令牌。
</Visibility>

交互式 API Playground 的凭证安全加固

Mintlify 的交互式 API 调试区（Playground）是一大核心卖点，但若处理不当，极易发生主密钥泄露或跨租户数据越权事故。

1. 通过 apiPlaygroundInputs 安全预填调试凭证

与其要求企业开发者频繁从生产控制台手动复制敏感密钥，不如通过认证会话自动注入已限制范围的沙箱凭据：

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

文档加载时，Mintlify 会自动将上述参数映射到 API 调试面板的请求头和查询参数中，实现“开箱即调”。

2. 生产落地安全军规

• 强制隔离沙箱与 Mock 节点： 在 docs.json 中配置 OpenAPI 服务器地址时，调试默认值务必指向沙盒环境或独立 Mock 服务，严禁直连生产集群数据库。
• 严禁注入长期有效的主密钥： apiPlaygroundInputs 注入的凭据应具备极短生命周期，并在鉴权网关层严格限定为只读或模拟调用权限。
• 利用 OpenAPI x-default 保底占位： 在未接入动态 JWT 认证的页面中，使用 OpenAPI 的 x-default 扩展字段定义占位提示（如 x-default: "YOUR_SANDBOX_KEY"），切忌将任何测试私钥硬编码提交至 Git 仓库。

生产发布前核对清单

• 域名独立性： 确认文档部署在专用二级子域名（如 docs.partner.example.com），而非不支持门禁拦截的子路径（/docs）。
• 认证范围核定： 根据业务公开程度，在 Access 后台明确启用全局锁定（Full）或局部锁定（Partial）。
• 签名密钥管控： 用于 ES256 签名的私钥已托管至加密机或 KMS，未混入代码库。
• Token 短时效： JWT 的 exp 声明已控制在 10 秒以内，防范网络截获重放风险。
• 权限分组闭环： 私有 API 页面已在 MDX Frontmatter 中严谨标注 groups。
• 调试端点降权： 交互式 Playground 已通过 apiPlaygroundInputs 绑定低权限沙箱凭据。
• 预览分支防护： Git 集成的 PR 预览环境已验证具备相同的身份拦截策略。

严格遵循上述架构与配置流程，工程团队不仅能为关键合作伙伴提供极致顺畅的现代化交互文档体验，还能构筑起坚实可靠的私有 API 零信任安全防线。

参考资料

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify