鉴权
CodeBox API 鉴权方式、权限列表与限流规则
获取 API Key
登录后在 Dashboard → API 管理 页面中创建 API Key。创建时可以选择名称和授予的权限范围。
API Key 仅在创建时完整显示一次，请立即保存。之后只能看到掩码版本。
鉴权方式
方式一：Bearer Token（推荐）
通过 Authorization Header 传递 API Key：
Authorization: Bearer cb_sk_xxxxxxxxxxxxxxxxcurl -X POST https://www.codebox.club/api/v1/plugin/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer cb_sk_xxxxxxxxxxxxxxxx" \
-d '{"content": "https://example.com"}'方式二：cb-api-key Header
旧版兼容方式，Plugin 端点同时支持：
cb-api-key: cb_sk_xxxxxxxxxxxxxxxxAPI Key 以 cb_sk_ 开头，请妥善保管，不要将其暴露在前端代码或公开仓库中。
权限列表
创建 API Key 时，需选择授予的权限：
| 权限 | 说明 |
|---|---|
qrcode:generate | 生成二维码、读取模板和统计数据，也用于 MCP Server 只读/生成工具 |
qrcode:create | 创建、更新或删除已保存的二维码；MCP 更新和删除工具必须具备此权限 |
公开的 /api/v1/qrcode/generate 接口无需认证即可调用。添加 API Key 后可获得更高的调用频率和更大的图片尺寸。
限流规则
API 根据用户类型实施不同的频率限制：
| 用户类型 | 频率限制 | 每日上限 | 最大尺寸 |
|---|---|---|---|
| 匿名用户 | 10 次/分钟 | — | 1000px |
| 登录用户 | 60 次/分钟 | — | 2000px |
| API Key | 60 次/分钟 | 1000 次/天 | 2000px |
API Key 的频率和每日上限由服务端策略确定，客户端不能在创建或更新 Key 时扩大限额。
同一账号创建的所有 API Key 共享同一个每日调用额度；更换或新增 Key 不会获得额外额度。每日额度按 UTC 日期重置。
当超出限制时，API 返回 429 状态码，响应 Header 中包含：
| Header | 说明 |
|---|---|
X-RateLimit-Limit | 当前时间窗口的总配额 |
X-RateLimit-Remaining | 剩余可用次数 |
X-RateLimit-Reset | 配额重置的 Unix 时间戳 |
错误码
| 状态码 | 说明 | 常见原因 |
|---|---|---|
| 401 | 未授权 | API Key 无效或已删除 |
| 403 | 权限不足 | API Key 缺少所需权限（如需要 qrcode:create 但只授予了 qrcode:generate） |
| 429 | 配额超限 | 超出频率限制或每日上限 |
错误响应示例：
{
"error": "Unauthorized",
"message": "Invalid or expired API Key"
}