令牌管理

用于管理你 BUZZ 账号下的 sk- API key —— 也就是平时调用 /v1/messages、/v1/chat/completions 时携带的那串 token。BUZZ 后台界面的「创建 / 改名 / 吊销 key」走的就是这组接口。

鉴权

所有 /api/token/* 接口都过 UserAuth 中间件。它接受两种身份:浏览器 dashboard 自带的 session cookie,或者更适合脚本调用的 Access Token。Access Token 是从用户设置页生成的另一种长期凭证,不是你平时用的 sk- API key。

Headers

Authorization: <YOUR_ACCESS_TOKEN>
Buzz-User: 1
Content-Type: application/json

端点列表

9 个端点覆盖一个 key 的完整生命周期,加 1 条用 sk- 鉴权的自查端点。

Token 对象

所有 list / get / update 端点都返回这个结构:

Status 常量

GET /api/token/

分页列出当前用户的所有 token。

查询参数

示例

curl 'https://buzzai.cc/api/token/?p=1&page_size=10' \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

响应

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 4,
    "items": [
      {
        "id": 21,
        "user_id": 1,
        "name": "cc",
        "key": "OnyH**********esAm",
        "status": 1,
        "created_time": 1779358699,
        "accessed_time": 1779778939,
        "expired_time": -1,
        "remain_quota": 0,
        "unlimited_quota": true,
        "used_quota": 18009,
        "model_limits_enabled": false,
        "model_limits": "",
        "allow_ips": null,
        "group": "default",
        "vendor_routes": "",
        "DeletedAt": null
      }
    ]
  }
}

GET /api/token/search

按 name 或 key 片段搜索。带 SearchRateLimit。

查询参数

支持 % 通配符。限制:%% 拒绝;每个表达式 % 数量上限 2;含 % 时去除 % 后关键词至少 2 个字符;用户的 token 总数达到 MaxUserTokens 时禁用模糊匹配。

示例

curl 'https://buzzai.cc/api/token/search?keyword=AWS&p=1' \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

响应结构与 GET /api/token/ 一致。

GET /api/token/:id

取单条 token 详情,key 字段已 mask。

示例

curl https://buzzai.cc/api/token/21 \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

响应

{
  "success": true,
  "message": "",
  "data": {
    "id": 21,
    "name": "cc",
    "key": "OnyH**********esAm",
    "status": 1,
    "...": "..."
  }
}

不存在跨用户读取问题 —— 查询条件锁定 (id, user_id),请求别人的 id 会以 not-found 形式返回。

POST /api/token/:id/key

返回完整未 mask 的 key。

示例

curl -X POST https://buzzai.cc/api/token/21/key \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

响应

{
  "success": true,
  "message": "",
  "data": {
    "key": "OnyHCHFmoxWEB0bIHS6Kc8RMI9ezNyBjG07kumzorg9tesAm"
  }
}

POST /api/token/

新建一个 token。

请求体

提交一个部分 Token 对象。服务端只读取以下字段构造新记录,其它(id、user_id、key、时间戳)都是后端生成的:

示例

curl -X POST https://buzzai.cc/api/token/ \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-runner",
    "expired_time": -1,
    "remain_quota": 0,
    "unlimited_quota": true,
    "model_limits_enabled": false,
    "model_limits": "",
    "group": "default",
    "vendor_routes": ""
  }'

响应

{
  "success": true,
  "message": ""
}

校验失败的两种情况:用户 token 总数已达 MaxUserTokens;vendor_routes 不是合法 JSON 或 key/value 为空。

PUT /api/token/

更新一个已有 token。

查询参数

请求体

id 必填。可写字段:name、expired_time、remain_quota、unlimited_quota、model_limits_enabled、model_limits、allow_ips、group、vendor_routes。其它字段被忽略。

状态切换规则:

• 从 3(Expired)切回 1(Enabled):若 expired_time 仍在过去 → 拒绝
• 从 4(Exhausted)切回 1(Enabled):若 remain_quota ≤ 0 且 unlimited_quota 为 false → 拒绝

示例:改名

curl -X PUT https://buzzai.cc/api/token/ \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 21,
    "name": "ci-runner-prod",
    "expired_time": -1,
    "remain_quota": 0,
    "unlimited_quota": true
  }'

示例:仅禁用(status_only)

curl -X PUT 'https://buzzai.cc/api/token/?status_only=1' \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{"id": 21, "status": 2}'

响应

{
  "success": true,
  "message": "",
  "data": { "id": 21, "name": "ci-runner-prod", "key": "OnyH**********esAm", "status": 1, "...": "..." }
}

DELETE /api/token/:id

软删除单条(GORM DeletedAt)。

示例

curl -X DELETE https://buzzai.cc/api/token/21 \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

响应

{ "success": true, "message": "" }

POST /api/token/batch

事务内一次性软删多条,Redis 缓存同时清理。

请求体

{ "ids": [21, 133, 656] }

响应

{
  "success": true,
  "message": "",
  "data": 3
}

data 是实际删除的行数。查询锁定 user_id = current_user,他人 id 会被静默跳过。

POST /api/token/batch/keys

批量取多个 token 的完整 key。带 CriticalRateLimit + DisableCache。

请求体

{ "ids": [21, 133] }

单次最多 100 个 id,超限返回 MsgBatchTooMany 错误。

响应

{
  "success": true,
  "message": "",
  "data": {
    "keys": {
      "21": "OnyHCHFmoxWEB0bIHS6Kc8RMI9ezNyBjG07kumzorg9tesAm",
      "133": "..."
    }
  }
}

GET /api/usage/token/(自查)

独立的一条 sk- key 自查端点,适合 SDK 在不接触管理 API 的情况下问「这把 key 还剩多少额度」。

鉴权

Authorization: Bearer sk-<YOUR_BUZZ_KEY>

响应

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "cc",
    "total_granted": 513586360,
    "total_used": 515813135,
    "total_available": -2226775,
    "unlimited_quota": true,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0
  }
}

注意这条端点用 {code, message, data} 包络,与其它端点的 {success, message, data} 不同。expired_time = -1 时 expires_at 返回 0。

工作流示例

端到端创建一把新 key

# 1. 创建
curl -X POST https://buzzai.cc/api/token/ \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-runner","expired_time":-1,"remain_quota":0,"unlimited_quota":true,"group":"default"}'

# 2. 拉列表或按 name 搜索找到新建条目的 id
curl 'https://buzzai.cc/api/token/search?keyword=ci-runner&p=1' \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

# 3. 取完整 key,写入你的 secret store(只取这一次)
curl -X POST https://buzzai.cc/api/token/<id>/key \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

轮换 key:先禁用旧的、再创建新的

# 1. 把旧 token 置为 Disabled(status=2)
curl -X PUT 'https://buzzai.cc/api/token/?status_only=1' \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{"id": 21, "status": 2}'

# 2. 走「端到端创建」流程拿到新 key

# 3. 新 key 部署完毕、确认无误后,硬吊销旧 token
curl -X DELETE https://buzzai.cc/api/token/21 \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1"

批量清理失效 key

# 1. 拉列表,客户端筛 status=3(Expired)或 status=4(Exhausted)
# 2. 批量删
curl -X POST https://buzzai.cc/api/token/batch \
  -H "Authorization: $BUZZ_ACCESS_TOKEN" \
  -H "Buzz-User: 1" \
  -H "Content-Type: application/json" \
  -d '{"ids":[101,102,103]}'

错误码

错误响应包络:

{
  "success": false,
  "message": "Unauthorized, New-Api-User header not provided"
}

注:i18n 文案里仍写着 New-Api-User,但实际读取的 header 是 Buzz-User。请发 Buzz-User。

相关链接

• POST /v1/messages — 用这里发出来的 key 调 Claude
• GET /api/user/self — 当前用户账号信息
• GET /api/user/dashboard — 额度与用量看板
• 鉴权指南