claude-code-hub/docs/api-authentication-guide.md

API 认证使用指南

📋 概述

Claude Code Hub 的所有 API 端点通过 HTTP Cookie 进行认证，Cookie 名称为 auth-token。

🔐 认证方式

方法 1：通过 Web UI 登录（推荐）

这是最简单的认证方式，适合在浏览器中测试 API。

步骤：

1. 访问 Claude Code Hub 登录页面（通常是 http://localhost:23000 或您部署的域名）
2. 使用您的 API Key 或管理员令牌（ADMIN_TOKEN）登录
3. 登录成功后，浏览器会自动设置 auth-token Cookie（有效期 7 天）
4. 在同一浏览器中访问 API 文档页面即可直接测试（Cookie 自动携带）

优点：

• ✅ 无需手动处理 Cookie
• ✅ 可以直接在 Scalar/Swagger UI 中测试 API
• ✅ 浏览器自动管理 Cookie 的生命周期

方法 2：手动获取 Cookie（用于脚本或编程调用）

如果需要在脚本、自动化工具或编程环境中调用 API，需要手动获取并设置 Cookie。

步骤：

1. 先通过浏览器登录 Claude Code Hub
2. 打开浏览器开发者工具（按 F12 键）
3. 切换到以下标签页之一：
   • Chrome/Edge: Application → Cookies
   • Firefox: Storage → Cookies
   • Safari: Storage → Cookies
4. 在 Cookie 列表中找到 auth-token
5. 复制该 Cookie 的值（例如：cch_1234567890abcdef...）
6. 在 API 调用中通过 HTTP Header 携带该 Cookie

优点：

• ✅ 适合自动化脚本和后台服务
• ✅ 可以在任何支持 HTTP 请求的环境中使用
• ✅ 便于集成到 CI/CD 流程

💻 使用示例

curl 示例

# 基本用法：通过 Cookie Header 认证
curl -X POST 'http://localhost:23000/api/actions/users/getUsers' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: auth-token=your-token-here' \
  -d '{}'

# 使用 -b 参数（curl 的 Cookie 简写）
curl -X POST 'http://localhost:23000/api/actions/users/getUsers' \
  -H 'Content-Type: application/json' \
  -b 'auth-token=your-token-here' \
  -d '{}'

# 从文件读取 Cookie
curl -X POST 'http://localhost:23000/api/actions/users/getUsers' \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{}'

JavaScript (fetch) 示例

浏览器环境（推荐）

// Cookie 自动携带，无需手动设置
fetch('/api/actions/users/getUsers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include', // 重要：告诉浏览器携带 Cookie
  body: JSON.stringify({}),
})
  .then(res => res.json())
  .then(data => {
    if (data.ok) {
      console.log('成功:', data.data);
    } else {
      console.error('失败:', data.error);
    }
  });

Node.js 环境

const fetch = require('node-fetch');

// 手动设置 Cookie
fetch('http://localhost:23000/api/actions/users/getUsers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'auth-token=your-token-here',
  },
  body: JSON.stringify({}),
})
  .then(res => res.json())
  .then(data => {
    if (data.ok) {
      console.log('成功:', data.data);
    } else {
      console.error('失败:', data.error);
    }
  });

Python 示例

使用 requests 库

import requests

# 方式 1：使用 Session（推荐，自动管理 Cookie）
session = requests.Session()
session.cookies.set('auth-token', 'your-token-here')

response = session.post(
    'http://localhost:23000/api/actions/users/getUsers',
    json={},
)

if response.json()['ok']:
    print('成功:', response.json()['data'])
else:
    print('失败:', response.json()['error'])

# 方式 2：直接在 headers 中设置 Cookie
response = requests.post(
    'http://localhost:23000/api/actions/users/getUsers',
    json={},
    headers={
        'Content-Type': 'application/json',
        'Cookie': 'auth-token=your-token-here'
    }
)

使用 httpx 库（异步支持）

import httpx

async def get_users():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            'http://localhost:23000/api/actions/users/getUsers',
            json={},
            headers={
                'Cookie': 'auth-token=your-token-here'
            }
        )
        return response.json()

# 使用示例
import asyncio
result = asyncio.run(get_users())

Go 示例

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "http://localhost:23000/api/actions/users/getUsers"

    // 创建请求体
    body := bytes.NewBuffer([]byte("{}"))

    // 创建请求
    req, err := http.NewRequest("POST", url, body)
    if err != nil {
        panic(err)
    }

    // 设置 Headers
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Cookie", "auth-token=your-token-here")

    // 发送请求
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // 解析响应
    respBody, _ := io.ReadAll(resp.Body)
    var result map[string]interface{}
    json.Unmarshal(respBody, &result)

    if result["ok"].(bool) {
        fmt.Println("成功:", result["data"])
    } else {
        fmt.Println("失败:", result["error"])
    }
}

⚠️ 常见问题

1. 401 Unauthorized - "未认证"

原因： 缺少 auth-token Cookie

解决方法：

• 确认请求中包含了 Cookie: auth-token=... Header
• 检查 Cookie 值是否正确（不要包含额外的空格或换行符）
• 在浏览器环境确保设置了 credentials: 'include'

2. 401 Unauthorized - "认证无效或已过期"

原因： Cookie 无效、已过期或已被撤销

解决方法：

• 重新登录获取新的 auth-token
• 检查用户账号是否被禁用
• 确认 API Key 是否设置了 canLoginWebUi 权限

3. 403 Forbidden - "权限不足"

原因： 当前用户没有访问该端点的权限

解决方法：

• 检查端点是否需要管理员权限（标记为 [管理员]）
• 使用管理员账号登录（使用 ADMIN_TOKEN 或具有 admin 角色的用户）

4. 浏览器环境 Cookie 未自动携带

原因： 未设置 credentials: 'include'

解决方法：

fetch('/api/actions/users/getUsers', {
  credentials: 'include', // 添加这一行
  // ... 其他配置
})

5. 跨域请求 Cookie 问题

原因： CORS 策略限制

解决方法：

• 确保 API 服务器配置了正确的 CORS 策略
• 在前端请求中设置 credentials: 'include'
• 使用相同域名或配置服务器允许跨域 Cookie

🔒 安全最佳实践

1. 不要在公共场合分享 Cookie 值

   • auth-token 相当于您的登录凭证
   • 泄露后他人可以冒充您的身份操作系统

2. 定期更换 API Key

   • Cookie 有效期为 7 天
   • 到期后需要重新登录

3. 使用 HTTPS

   • 生产环境务必启用 HTTPS
   • 确保 ENABLE_SECURE_COOKIES=true（默认值）

4. 环境变量管理

   • 将 Cookie 值存储在环境变量中
   • 不要硬编码在代码仓库中

📚 相关资源

• OpenAPI 文档 - Swagger UI
• Scalar API 文档 - 现代化 API 文档界面
• GitHub 仓库 - 查看源码和更多文档