Skip to content

api-authentication-guide.md

Latest commit

 

History

History
197 lines (146 loc) · 5.47 KB

api-authentication-guide.md

File metadata and controls

197 lines (146 loc) · 5.47 KB

API 认证使用指南

概述

Claude Code Hub 的新版管理 API 位于 /api/v1/*。它和代理 API /v1/* 互相独立，也和已弃用的 Server Action 适配层 /api/actions/* 独立。

新版管理 API 支持三种凭据传递方式：

  • Cookie session：Cookie: auth-token=<session>
  • Bearer token：Authorization: Bearer <token>
  • 用户 API Key：X-Api-Key: <key>

访问权限按路由分为三层：

  • public：无需认证，例如 GET /api/v1/public/status。
  • read：接受有效 session、ADMIN_TOKEN 或任意有效用户 API Key。
  • admin：默认接受有效 session Cookie、opaque session bearer token 和 ADMIN_TOKEN。用户 API Key 仅在 ENABLE_API_KEY_ADMIN_ACCESS=true 且属于 admin 用户时可调用 admin 路由。

Cookie 认证的写操作需要 CSRF 保护：先调用 GET /api/v1/auth/csrf，再在 POST、PUT、PATCH、DELETE 请求中携带 X-CCH-CSRF。Bearer 和 X-Api-Key 请求不需要 CSRF header。

生产环境建议显式配置 CSRF_SECRET。多副本部署必须让所有实例使用同一个 CSRF_SECRET，否则一个实例签发的 cookie 写操作 token 可能无法被另一个实例验证。

旧版 /api/actions/* 仍可用但已弃用，响应会带标准 Deprecation、Sunset 与指向 /api/v1/openapi.json 的 successor Link。设置 ENABLE_LEGACY_ACTIONS_API=false 后，旧 action 执行接口返回 410 application/problem+json。

Cookie Session

适合浏览器内测试和 Scalar/Swagger UI。

  1. 访问 Claude Code Hub 登录页面。
  2. 使用 ADMIN_TOKEN 或允许 Web UI 登录的用户 API Key 登录。
  3. 浏览器会设置 auth-token Cookie。
  4. 在同一浏览器访问 /api/v1/scalar 或 /api/v1/docs，文档页会自动携带 Cookie。

Cookie 写操作示例：

csrf_token="$(curl -s 'http://localhost:13500/api/v1/auth/csrf' \
  -b 'auth-token=your-session-token' | jq -r '.csrfToken')"

curl -X PATCH 'http://localhost:13500/api/v1/users/1' \
  -H 'Content-Type: application/json' \
  -H "X-CCH-CSRF: ${csrf_token}" \
  -b 'auth-token=your-session-token' \
  -d '{"note":"updated by REST API"}'

浏览器 fetch 示例：

const csrf = await fetch("/api/v1/auth/csrf", {
  credentials: "include",
}).then((res) => res.json());

const user = await fetch("/api/v1/users/1", {
  method: "PATCH",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
    "X-CCH-CSRF": csrf.csrfToken,
  },
  body: JSON.stringify({ note: "updated by REST API" }),
}).then(async (res) => {
  if (!res.ok) throw await res.json();
  return res.json();
});

console.log(user);

Bearer Token

适合脚本、CLI 和服务端 SDK。

curl 'http://localhost:13500/api/v1/users?limit=20' \
  -H 'Authorization: Bearer your-session-or-admin-token'

Node.js 示例：

const response = await fetch("http://localhost:13500/api/v1/users?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.CCH_TOKEN}`,
  },
});

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.errorCode}: ${problem.detail}`);
}

const page = await response.json();
console.log(page.users ?? page.items ?? page);

X-Api-Key

适合第三方工具读取自身范围内的数据。

curl 'http://localhost:13500/api/v1/me/quota' \
  -H 'X-Api-Key: your-user-api-key'

admin 路由默认不接受用户 API Key。确需允许第三方管理工具通过 admin 用户 API Key 调用管理端接口时，必须显式设置：

ENABLE_API_KEY_ADMIN_ACCESS=true

开启后仍要求该 API Key 对应的用户角色为 admin。普通用户 API Key 不能调 admin 路由。

响应格式

成功响应直接返回资源或列表对象，不再使用 legacy { ok, data } 包装。

{
  "users": [
    {
      "id": 1,
      "name": "admin",
      "role": "admin"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

失败响应使用 application/problem+json：

{
  "type": "urn:claude-code-hub:problem:auth.forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Admin access is required.",
  "instance": "/api/v1/providers",
  "errorCode": "auth.forbidden",
  "errorParams": {}
}

前端和第三方客户端应优先使用 errorCode 和 errorParams 做错误分支与本地化， 不要依赖 detail 的展示语言。

常见问题

401 Unauthorized

请求没有携带凭据，或凭据无效、过期、已撤销。

处理方式：

  • Cookie 模式确认请求携带 Cookie: auth-token=...。
  • 浏览器 fetch 确认设置 credentials: "include"。
  • Bearer 模式确认使用 Authorization: Bearer <token>。
  • X-Api-Key 模式确认 key 未被禁用、未过期。

403 Forbidden

当前身份没有访问该路由的权限。

处理方式：

  • admin 路由使用管理员 session 或 ADMIN_TOKEN。
  • 用户 API Key 调 admin 路由前确认 ENABLE_API_KEY_ADMIN_ACCESS=true，且 key 所属用户为 admin。
  • Cookie 写操作确认已携带当前 session 对应的 X-CCH-CSRF。

404 Not Found

资源不存在，或该资源属于已隐藏/已弃用类型。新版 /api/v1 不暴露 claude-auth 与 gemini-cli provider 类型。

相关资源

  • OpenAPI JSON：/api/v1/openapi.json
  • Swagger UI：/api/v1/docs
  • Scalar UI：/api/v1/scalar
  • Public Status API：public-status-api.md
  • API Key admin access 安全说明：security/api-key-admin-access.md
  • GitHub 仓库：https://github.com/ding113/claude-code-hub