鉴权体系说明（Auth）

说明

后台管理接口采用多级鉴权机制，权限级别从低到高为：公开、用户、管理员、Root。

不同接口使用的认证方式略有差异，请根据本页说明对号入座。

认证方式

后台管理接口主要使用以下两种认证方式之一，注意两种 Token 是不同的，不能混用：

一、系统访问令牌（PAT） + New-Api-User

适用于绝大多数后台管理接口（用户管理、令牌管理、日志查询等）。

在请求头中同时携带：

Authorization: Bearer {system_access_token}
New-Api-User: {user_id}

• {system_access_token}：在「个人设置 - 安全设置 - 系统访问令牌」中生成的 32 位字符串，不是 sk-xxx 形式的 API Key。
• {user_id}：当前登录用户的 ID，必须与令牌所属用户匹配。
• Authorization 中的 Bearer 前缀可省略，直接传 Token 也可以。
• 浏览器登录态下也可以用 Cookie Session 调用，但仍然需要携带 New-Api-User。

二、API Key（sk-xxx）

仅用于"以令牌身份查询自身信息"的接口，例如：

• GET /api/usage/token/ — 获取令牌使用情况
• GET /api/log/token — 通过令牌获取日志

只需在请求头中携带 API Key 即可，不需要 New-Api-User：

Authorization: Bearer sk-xxxxxx

• API Key 在「控制台 - 令牌管理」中创建，形如 sk-xxxxxx。
• 此类接口的中间件直接根据 API Key 自身识别用户，因此 New-Api-User 请求头会被忽略。

权限级别

• 公开（Public）：无需鉴权。
• 用户（User）：需要登录态或系统访问令牌（PAT）。
• 管理员（Admin）：需要管理员权限的账号对应的 PAT 或登录态。
• Root：需要 Root 账号对应的 PAT 或登录态。

常见错误

• ❌ 用 sk-xxx API Key 调用需要 PAT 的管理接口（如 /api/token/、/api/user/self） — 会鉴权失败。
• ❌ 用 PAT 调用 /api/usage/token/、/api/log/token 时还附带 New-Api-User — 这两个接口只看 Authorization 中的 API Key，附带的用户头不会生效。
• ❌ 漏掉 New-Api-User 请求头去调用需要 PAT 的接口 — 会被中间件直接拦截返回 401。