认证设置

启用认证后，用户需先登录才能访问你的文档。

启用认证后，用户必须先登录才能访问任何内容。你可以将特定页面或分组配置为公开，而将其他页面设为受保护状态。

认证仅适用于托管在自定义域名或 Mintlify 子域名上的站点。例如，docs.example.com 或 example.mintlify.site。使用自定义子路径的站点不支持认证。例如，example.com/docs。

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

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

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

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

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

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

当你使用 OAuth 或 JWT (JSON Web Token) 进行认证时，可以将特定页面仅限于某些用户组访问。若希望不同用户根据其角色或属性查看不同内容，这将非常有用。

通过在认证过程中传递的用户数据来管理 groups。详见 用户数据格式。

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

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

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

用户必须至少属于所列的一个 groups 才能访问该页面。如果用户在不具备所需分组的情况下尝试访问页面，将会收到 404 错误。

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

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

当使用 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>;
  };
};

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