鉴权
浏览器会话与 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 / account 四种权限，每个端点按需检查：
| 权限 | 覆盖的操作 |
|---|---|
read | 公开读取（仓库快照、对象、证明等） |
write | 提交论文、Fork、加星、求复现等互动 |
run | 发起复现（POST /api/runs） |
权限不足时返回 403：
{ "error": "API Key 没有所需权限" }在请求中使用
把 Key 放进 x-api-key 请求头：
curl "https://citeark.co/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。
密钥管理支持 GET /api/account/keys、POST /api/account/keys、DELETE /api/account/keys，均要求 account 权限。创建请求包含 name、expiresIn（秒）和 permissions 数组；删除请求包含 keyId。新密钥的权限不能超过调用密钥，且到期时间不能更晚。
管理员可在密钥页面勾选“管理员密钥”，或创建包含 admin 权限的密钥。每次管理员 API 调用同时验证密钥权限和账号当前角色；管理员被降级后，原密钥立即失去管理能力。普通密钥不会自动获得管理员权限。
账号资料、头像、通知、仓库管理及作者认领均支持密钥。组织、邀请、设备、密码和两步验证接口位于 /api/auth/**，要求 account 权限；其机器可读接口定义位于 /api/auth/open-api/generate-schema。密码、验证码、第三方授权以及支付确认仍按原业务规则执行。
旧密钥不会自动增加 account 或 admin 权限，请在密钥页面创建所需的新密钥。完整业务接口目录见 /api/openapi.json 和平台操作。
安全建议
- Key 等同于密码：不要写进代码、不要提交到 Git，用环境变量或密钥管理工具注入；
- 怀疑泄露时立刻在 Agent API Key 页面撤销并重建；
- 为不同用途创建不同名字的 Key，便于在用量列表中追溯来源，也可以单独撤销其中一把。
account 用于密钥、密码、账号注销、登录会话和认证设置；admin 用于全部 /api/admin/** 接口。请求也支持 Authorization: Bearer <key>。