主题
API Key 管理
API Key 是调用 MCP 和 HTTP API 的唯一凭证。
Key 的格式
Keepamore API Key 统一以 km_ 开头，后跟 32 位字符，总长 35：
km_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx任何不匹配此格式的字符串都会被服务端立即拒绝（401 API Key 格式无效）。
获取 API Key
- 登录 Keepamore 主站，如果没有账号，请先注册账号
- 进入
Keepamore API/MCP 管理页的 API Key 标签页 - 首次访问时系统会自动创建一个 Key
- Key 可随时在管理页查看和复制
三种传入方式
服务端允许以下任意一种位置携带 Key（多处同时传入且值不一致会报错）：
| 方式 | 请求头 / Query | 推荐度 |
|---|---|---|
| 自定义头 | X-API-Key: km_xxx | ✅ 推荐 |
| Bearer 头 | Authorization: Bearer km_xxx | ✅ 推荐 |
| URL 参数 | ?key=km_xxx | ⚠️ 兼容keepa的写法； |
重置 API Key
点击 API Key 页的"重置"按钮：
- 系统生成一把新 Key，旧 Key 进入 30 分钟延迟失效倒计时
- 新 Key 可随时在管理页查看和复制
- 30 分钟内新旧 Key 同时有效——用于在不中断业务的前提下切换客户端配置
- 倒计时结束后旧 Key 立即失效，任何请求返回 403
何时应该重置？
- 疑似泄漏（误提交到代码仓库、在截图中露出）
- 团队成员变动
- 定期轮换（安全最佳实践，建议 3–6 个月一次）
Key 的状态与限制
- 每个账号当前只支持一把活跃 Key（不含重置后 30 分钟内的旧 Key）
- Key 永不过期，只会被重置或禁用
- 服务端会记录每把 Key 的最后使用时间和最后使用 IP，可在管理页查看——异常 IP 是泄漏的常见信号
不要做的事
- ❌ 把 Key 写死在前端 / 浏览器扩展中（任何用户都能读出）
- ❌ 把 Key 提交到公开仓库——GitHub secret scanning 会很快被爬到并遭刷
- ❌ 用 URL
?key=方式在生产环境调用 - ❌ 多处同时传入不同的 Key（服务端会 400 拒绝）
推荐做法
- ✅ 服务器端通过环境变量读取：
KEEPAMORE_API_KEY - ✅ CI/CD 中使用 secret store
- ✅ Cherry Studio / Claude Desktop 等客户端填入
X-API-Key头 - ✅ 定期查看管理页的"最后使用 IP"，发现异常立即重置