Developer API

Developer API 是 Manifest 控制的可选模块，默认关闭。启用后，登录用户可在 /developer 创建、查看摘要、轮换和撤销个人 API Key；首个稳定 endpoint 是 GET /v1/me。

创建和保存 Key

每个用户最多拥有 2 个 active Key；轮换会把旧 Key 转为最多继续可用 24 小时的 rotating 状态，并签发新的 active Key。同一用户同时只允许一个 rotating 重叠，必须等它到期或先撤销旧 Key 后再轮换。创建或轮换成功时，页面只显示一次完整的 bo_sk_... 明文；离开或刷新页面后无法恢复。D1 只保存 SHA-256 hash、短 prefix、名称、scope、状态和时间，不保存完整 Key。

请立即将明文保存到密码管理器或部署平台的 secret store。不要提交到 Git、写入客户端 bundle、URL、Analytics、错误报告或普通日志。

Key 默认在创建后 90 天过期。显式撤销立即生效。轮换会签发新 Key，并让旧 Key 最多继续有效 24 小时；应在重叠期内更新调用方，然后撤销旧 Key。

调用 v1

所有公开 API 只接受 HTTP Bearer，不接受浏览器 Session：

curl https://example.com/v1/me \
  --header "Authorization: Bearer $BO_STARTER_API_KEY"

GET /v1/me 要求 account:read scope，只返回 Key owner 自己的 id、name、email 和 createdAt。

成功响应：

{
  "data": {
    "id": "user-id",
    "name": "Ada",
    "email": "ada@example.com",
    "createdAt": "2026-07-22T00:00:00.000Z"
  },
  "meta": {
    "correlationId": "00000000-0000-4000-8000-000000000021"
  }
}

错误响应使用稳定 envelope：

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is invalid or expired.",
    "correlationId": "00000000-0000-4000-8000-000000000021"
  }
}

调用方应按 HTTP status 和 error.code 分支，不解析自由文本。correlationId 可用于支持排查，但不代表用户或 Key 身份。

Scope 和限流

首版只注册 account:read。缺少 scope 返回 403 / INSUFFICIENT_SCOPE；不存在的版本返回 404 / UNSUPPORTED_API_VERSION；无效、过期或已撤销 Key 返回 401 / INVALID_API_KEY。

每个有效 Key 限制为 60 requests/minute，瞬时 burst 为 10。超过限制返回 429 / RATE_LIMIT_EXCEEDED，并通过 Retry-After 响应头给出等待秒数。调用方应等待后重试，并使用有上限的退避；不要并发重放。无效 Key 另按来源 IP hash 使用更低速保护。

使用记录只保存 endpoint category、结果、时间和可选 Key ID，不保存请求 body、完整 Key、Authorization、账号字段或自由错误文本。