鉴权
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 | 创建并保存二维码记录（含追踪短链），可在后台管理 |
公开的 /api/v1/qrcode/generate 接口无需认证即可调用。添加 API Key 后可获得更高的调用频率和更大的图片尺寸。
限流规则
API 根据用户类型实施不同的频率限制：
| 用户类型 | 频率限制 | 每日上限 | 最大尺寸 |
|---|---|---|---|
| 匿名用户 | 10 次/分钟 | — | 1000px |
| 登录用户 | 60 次/分钟 | — | 2000px |
| API Key | 60 次/分钟 | 1000 次/天 | 2000px |
当超出限制时，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"
}