鉴权与安全

哪些接口需要 API Key

资源	是否需要 Key
API 发现、卡牌、卡背	否
公开卡组列表和详情	否
自己的卡组读取、创建、修改、校验、替换和删除	是

API Key 的格式以 kd_ 开头。请求时使用标准 Bearer 头：

Authorization: Bearer <kd_api_key>

不要使用查询参数传递密钥。

创建 API Key

1. 登录 KARDS Decker。
2. 打开个人中心 → API 与授权 → API Key。
3. 选择只读或完整卡组权限，再选择有效期。
4. 创建后立即复制；原始 Key 只显示一次。

有效期为 1 至 365 天，网站默认提供 30、90 和 365 天选项。已撤销或过期的 Key 会立即失效。

权限范围

Scope	允许的操作
decks:read	列出和读取自己的卡组；所有 Key 都必须包含
decks:write	创建、更新、校验卡组以及执行卡牌替换
decks:delete	删除自己的卡组

个人中心的“只读卡组”只授予 decks:read；“完整卡组权限”授予以上三项。

找到 user_id

受限路径形如：

/api/v1/users/:user_id/decks

这里的 user_id 不是昵称。它是登录后个人中心“机密信息”区域里的“军籍编号（UID）”，格式为 UUID，例如：

123e4567-e89b-42d3-a456-426614174000

API 会同时验证 Key 的所属用户。把别人的 UUID 放入路径不会扩大权限，只会得到 403 user_mismatch。

安全清单

• 只向后端服务、命令行工具或受信任的本地程序提供 Key。
• 不要把 Key 写进浏览器前端包、URL、Git 仓库、错误日志或截图。
• 生产服务用环境变量注入 Key，并在日志记录前删除 Authorization。
• 按最小权限创建 Key；只读集成不要选择完整权限。
• 怀疑泄露时，在个人中心撤销旧 Key 并创建新 Key。

不要把 Key 放进公开前端

浏览器发出的请求和构建后的 JavaScript 都可以被用户查看。需要长期保密的 Key 应由你自己的后端持有。