认证
申请 OpenAPI Key 与请求时携带 Token 的方式。
两种身份
OpenAPI 支持两种调用身份：
| 身份 | 拿到方式 | 适用 |
|---|---|---|
| OpenAPI Key（推荐） | 在 设置 → OpenAPI 自助申请 | 服务端调用、CLI、智能体长期接入 |
| 登录会话 Cookie | 浏览器登录后自动持有 | 网页前端 / 同站 fetch |
OpenAPI Key 是大多数对外集成的标准方式。一个账户可拥有多个 Key，每个 Key 可独立命名、限定 scope、随时撤销。
申请 OpenAPI Key
- 登录 bestblogs.dev
- 进入 设置 → OpenAPI → 「创建新 Key」
- 给 Key 命名（例如「我的智能体」「Notion 集成」）
- 选择 scope（默认
read:public；如需写入收藏 / 划线，勾选write:capture） - 复制生成的 Key（仅此一次显示），妥善保管
请求格式
所有 OpenAPI 请求都需要在 HTTP header 中携带：
Authorization: Bearer <YOUR_OPENAPI_KEY>
示例（curl）：
curl https://bestblogs.dev/api/v2/resources?limit=10 \
-H "Authorization: Bearer bb_live_xxxxxxxxxxxx"
配额与限流
| 端点族 | 限流 |
|---|---|
| Discover（发现） | 60 req/min（免费）/ 600 req/min（Pro） |
| Read（阅读） | 30 req/min / 300 req/min |
| Capture（沉淀，写入） | 30 req/min / 300 req/min |
| AI 伴读 / Copilot | 与站内 AI 配额共享，按 token 计费 |
超出限流时返回 429 Too Many Requests，响应 header 包含 Retry-After（秒）。
安全建议
- 永不写在前端：OpenAPI Key 等同密码，禁止写入网页前端代码或开源仓库。
- 用环境变量：服务端 / CLI 用
BESTBLOGS_API_KEY等环境变量加载。 - 最小 scope：只勾选实际需要的写入权限。
- 定期轮换：怀疑泄露立即在 设置 → OpenAPI 撤销并新建。
错误码速查
| 状态码 | 含义 |
|---|---|
401 Unauthorized |
Key 缺失或无效 |
403 Forbidden |
Key 有效但 scope 不允许该端点（例如用 read:public 调写入接口） |
404 Not Found |
资源不存在或对你不可见 |
429 Too Many Requests |
触发限流，按 Retry-After 等待 |
5xx |
服务端临时错误，支持指数退避重试 |