API Key

key 是一串只有你和服务器知道的字符串，请求时放在 Authorization 头里。服务器只存它的 SHA-256，所以明文丢了找不回来，只能轮换。

Authorization: Bearer mcp_radar_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

怎么拿到一把

控制台里 /console/api-keys（管理员代签发走 /dashboard/api-keys）：

账号必须已经验证邮箱——这是挡住批量小号的那道门。

填名字、勾 scope。名字只给自己看，用来记住「这把给哪个 CI 用」。

复制明文。它只出现这一次。

自助签发的限制：两次之间至少间隔 60 秒，一个账号最多 5 把未失效的 key。上限不是配额，是「每把 key 都得有人管」—— 不再用的先吊销，数量就腾出来了。

档位决定的是默认配额和能勾哪些 scope，不是权限大小。

档位	谁签发	有主人吗	默认配额（分钟 / 天）	自助可勾的 scope
`user`	本人，或管理员代签	有（`userId`）	30 / 1000	只读 + 登记自己仓库的三个
`service`	仅管理员	无（接入方凭据）	60 / 5000	全部五个

两者是互斥的：有主人就必然是 user，无主人必然是 service。签发时不要自己拼这个组合——接口会直接拒绝 service + 主人，因为那样一把 key 会同时被「按主人查」和「按档位查」两套逻辑管住，交集说不清。

读多写少用 user 档就够；要在后台批量跑、每天会打满 1000 次的，找管理员开 service 档。

scope 只管能不能调这个接口，与配额无关。配额看档位。

scope	允许你做什么	自助可勾
`repos:read`	读仓库档案与区间统计（`/api/v1/repos*`）	✅
`repos:write`	`POST /api/v1/repos` 登记仓库（不发布）	✅
`rankings:read`	读排行与周期目录（`/api/v1/rankings/*`）	✅
`subscriptions:write`	创建订阅、指定任意回调地址	❌
`projects:write`	`POST /api/v1/projects` 把仓库发布到公开站	❌

后两个不进自助范围，理由是同一个：它们给的不是「操作自己的数据」。

需要它们就找管理员，逐把 key 开。

key 不要出现在前端代码里

凡是进了浏览器包的字符串都算公开。写入接口的 key 只该待在服务端、CI 的 secret 或本地 shell 里。

轮换会吊销旧的、签发一把新的，同一个事务里完成——旧的立刻失效，不存在两把同时能用的窗口。新的明文同样只显示一次。适合「按周期换」或者「怀疑可能泄露」。

吊销让这把 key 立刻返回 401 key_revoked。行不会被删：审计和「它为什么不见了」还要靠它回答。

过期由签发时决定。自助签发不设过期——给用户一个「到期必须回来续」的负担只会把人推向管理员去要一把长过期的 key。

先吊销那把 key，再谈别的。鉴权每次都读库，吊销即刻生效，没有缓存要等。

确认它调过什么：管理员那边的审计日志记了每把 key 的创建、改权限、吊销。

重新签发一把，把新的放进原来的位置。

响应里的 ratelimit-* 头、以及每个状态码代表什么，见调用、限流与错误；每个 scope 能打开哪些端点，见 API 参考 里的逐端点页。