三层鉴权，按家族区分
不同家族面向不同调用方，鉴权方式不同。请按你要访问的家族选择对应方式，不要混用。
| 家族 | 鉴权方式 | 适用调用方 |
|---|---|---|
| /api/v1/* | Bearer API 密钥（qf_live_ 前缀），按端点校验作用域 | 第三方集成、脚本、自有后端 |
| /api/developer/* | 用户会话 JWT（Authorization: Bearer 登录令牌）+ 开发者状态门 | 插件开发者本人操作 |
| /api/shared-index/* | 用户会话 JWT + 团队归属门（team gate） | 团队成员协同共享索引 |
| /api/signing-keys/* | 公开（无鉴权），用于验证插件包签名 | 任何需要验签的一方 |
作用域模型
v1 各端点按 read:<资源> 逐个授权（如 read:orders）；/api/v1/me 不需要作用域。粗粒度的 read 等价于全部只读作用域。作用域不足返回 403 insufficient_scope，响应体会列出 required、missing 与 declared，便于自助排查。
| 作用域 | 放行端点 |
|---|---|
| read:favorites | /api/v1/favorites |
| read:history | /api/v1/history |
| read:devices | /api/v1/devices |
| read:subscription | /api/v1/subscription |
| read:orders | /api/v1/orders |
| read:invoices | /api/v1/invoices |
| read:submissions | /api/v1/submissions |
| read:usage | /api/v1/usage |
| read | 粗粒度只读：等价于上面全部作用域，并覆盖 /api/v1/webhooks 的读写操作 |
| 无需 | /api/v1/me |
一个容易踩的点
Webhook 的创建、修改、删除与重投，当前源码里要求的是粗粒度 read，不是单独的 write:webhooks。也就是说：只勾了 read:favorites 的密钥调不动 webhooks，而带 read 的密钥能做全部 webhook 操作。创建密钥时按最小权限勾选。
密钥安全
qf_live_ 前缀为生产密钥，请只在服务端使用，切勿写入前端代码、仓库或日志。浏览器端调用请改由你的服务端中转。发现泄露请立即在控制台吊销并轮换。
1
最小权限
按端点勾选用到的作用域，不要图省事全勾 read。密钥泄露时，作用域就是损失半径。
2
一处存储，多处引用
放进你的密钥管理服务（Vault / Secrets Manager / CI 加密变量），代码里只读环境变量，不进版本库。
3
定期轮换
建议每 90 天轮换一次；轮换时先建新密钥、灰度切流、再吊销旧密钥，不要原地替换。