API 密钥

Legate API 密钥是业务应用访问模型代理的凭据。它同时认证调用方，并把调用方限制在显式绑定的模型组集合中。

API 密钥以 sk-leg- 开头；Sidecar Token 以 sc-leg- 开头；两者不能互换。

认证与授权

每个 API 密钥属于一个 Workspace，并绑定一个或多个模型组。一次请求按以下顺序处理：

1. 从 Authorization: Bearer 提取明文密钥；
2. 计算 SHA-256 并查找启用的密钥记录；
3. 用密钥所属 Workspace 解析请求中的模型组；
4. 检查密钥是否绑定该模型组 ID；
5. 检查模型组状态与入站 Contract，随后进入路由。

唯一受支持的调用方认证形式是：

Authorization: Bearer sk-leg-...

不要使用 X-Api-Key、Api-Key、query string 或 Cookie 传 Legate API 密钥。Driver 可能要求 Core 给上游注入厂商特定 X-Api-Key，那是另一条凭据边界。

创建与存储

创建响应返回一次完整密钥。之后 Central 只保存 SHA-256 hash、固定前缀与末尾 6 个字符；列表和详情不能恢复明文。Sidecar 快照同样只包含 hash 和授权元数据。

完整密钥只显示一次

丢失时创建新密钥并撤销旧密钥。不要尝试从数据库、浏览器或日志恢复明文。

状态与轮换

• enabled：可以认证并调用已授权模型组；
• disabled：拒绝新的模型调用；
• 删除：永久移除密钥记录。

推荐先创建绑定相同模型组的新密钥，完成所有客户端切换，再禁用和删除旧密钥。Sidecar 通过周期快照接收变更，因此紧急撤销时还要检查各实例最近拉取与 revision。

最小权限

• 每个应用、环境和部署单元使用独立密钥；
• 只绑定实际需要的模型组；
• 不把密钥写入源码、镜像、URL 或命令行参数；
• 用 Secret Manager 或等价机制注入；
• 通过 lastUsedAt 和运行统计辅助轮换，但不要记录完整认证头。