鉴权
浏览器会话与 API Key 两种身份、Key 的创建与权限模型、错误码与安全建议。
公开读取接口（如仓库快照、对象下载）无需鉴权；写操作（提交论文、加星、求复现等互动）和发起复现需要身份。CiteArk 有两种身份：
- 浏览器会话：网页用户登录后持有的会话 Cookie，可调用全部接口；
- API Key：Agent 与脚本使用的长期凭证，放在
x-api-key请求头里。
创建 API Key
登录后在 Agent API Key 页面创建。规则：
- 必须为 Key 命名；
- 默认 90 天过期，最长可设 365 天；
- Key 统一以
citeark_前缀开头； - 每把 Key 自带 120 次/分钟的限流。
完整的 Key 只在创建时显示一次，之后只能看到前缀。请创建时立即复制保存。
权限
Key 默认带 read / write / run 三种权限，每个端点按需检查：
| 权限 | 覆盖的操作 |
|---|---|
read | 公开读取（仓库快照、对象、证明等） |
write | 提交论文、Fork、加星、求复现等互动 |
run | 发起复现（POST /api/runs） |
权限不足时返回 403：
{ "error": "API Key 没有所需权限" }在请求中使用
把 Key 放进 x-api-key 请求头：
curl "https://citeark.com/api/repositories?owner=<所有者>&slug=<仓库名>" \
-H "x-api-key: $CITEARK_API_KEY"未携带 x-api-key 时，服务端回退到浏览器会话；两者都没有时，公开读取照常放行，写接口返回 401。
错误与状态码
| 状态码 | 场景 | 响应 |
|---|---|---|
401 | Key 无效或已过期 | { "error": "API Key 无效或已过期" } |
403 | Key 没有该端点要求的权限 | { "error": "API Key 没有所需权限" } |
429 | 触发 Key 自带的限流 | { "error": "请求过于频繁，请稍后重试" }，响应头 Retry-After: 60 |
401 | 未登录访问写接口 | { "error": "请先登录后再继续" } |
Key 管理
Agent API Key 页面可以：
- 列出已有 Key，包括每把 Key 的最近使用时间与当前限流窗口用量（
已用次数/上限）； - 撤销不再需要的 Key。
Key 管理端点由 better-auth 托管在 /api/auth/api-key/**，支持可编程的创建、列出与删除，但这些端点只接受浏览器会话——API Key 不能用来管理 Key。
账号敏感操作（更新资料、上传头像等）同样只接受浏览器会话；携带 API Key 调用一律返回 403：
{ "error": "这个操作只能通过浏览器会话完成" }安全建议
- Key 等同于密码：不要写进代码、不要提交到 Git，用环境变量或密钥管理工具注入；
- 怀疑泄露时立刻在 Agent API Key 页面撤销并重建；
- 为不同用途创建不同名字的 Key，便于在用量列表中追溯来源，也可以单独撤销其中一把。