身份验证

Orion Public API 使用 Bearer API Key。Key 代表调用方身份和 scope，不能代表最终资源授权；服务端仍会校验当前租户与资源所有权。

发送凭证

把 Key 放在 Authorization header：

Authorization: Bearer $ORION_API_KEY

不要通过 query string、URL、Cookie、日志或前端持久化发送 Key。

存储规则

• 生产 Key 放入服务端 Secret Manager，不进入源码、镜像和 fixture。
• 浏览器页面不直接持有生产 Key；由你的服务端调用 Orion API。
• Sandbox 与 Production 使用不同凭证、不同允许范围和独立轮换计划。
• 日志只记录 Key 的内部引用或末尾四位，不能记录完整值。

Scope 与最小权限

每个 Key 只授予真实业务链需要的 scope。示例：只读客户同步只需要 crm.customers:read，不应获得创建销售订单或读取财务报表的权限。

权限失败返回 403 和稳定 code。不要根据按钮是否显示来判断服务端权限，也不要假设知道资源 ID 就可以访问资源。

轮换

推荐使用重叠窗口：

1. 创建新 Key，并配置相同或更小的 scope。
2. 在调用方 Secret Manager 中部署新 Key。
3. 观察新 Key 的成功调用和错误率。
4. 撤销旧 Key，确认没有剩余调用。

如果 Key 疑似泄漏，应立即撤销，不等待常规轮换窗口。

排查 401

依次确认：

1. Header 是否使用 Bearer，且没有把环境变量名称当成真实值。
2. Key 是否属于当前环境，是否已过期或被撤销。
3. 请求是否经过代理；代理不得丢弃 Authorization。
4. 使用响应中的 request_id 联系支持，切勿同时发送完整 Key。