鉴权与密钥
了解鉴权方式、密钥数量上限、可用模型、有效期、停用与删除。
怎么鉴权
网关接口用 API 密钥鉴权，常用写法：
Authorization: Bearer sk-mh-...也可以把密钥放在 X-Api-Key 或 X-Goog-Api-Key 头里，分别对应 Anthropic 与 Gemini 官方 SDK 的写法。同时带了多个时，依次取 X-Api-Key、X-Goog-Api-Key、Authorization。
网关对整把密钥算摘要后查找，不解析前缀；密钥只用于网关鉴权，不会转发给上游。新建、停用、删除和修改都在几秒内对网关生效。
鉴权失败时
| 状态 | code | 原因 |
|---|---|---|
| 401 | invalid_api_key | 没带密钥，或密钥无效、已停用、已删除、已过期 |
| 403 | model_not_allowed | 请求的模型不在这把密钥的可用模型里 |
| 402 | insufficient_quota | 密钥所花的预算已用完：个人密钥花本人当月的预算，项目密钥花项目预算 |
表中是 OpenAI 格式的 error.code。错误体跟随所调用的协议，例如 Anthropic 格式里对应的 error.type 是 authentication_error、permission_error 和 billing_error。预算用完只拦截计费接口，/v1/models 和 /v1/messages/count_tokens 照常可用。
密钥类型与数量
在「我的密钥」新建的是个人密钥，花本人的预算。项目密钥和项目服务密钥花项目预算：项目密钥归某位成员所有，也列在其「我的密钥」里，详情标为「项目密钥」；项目服务密钥供程序使用，不属于任何人。
每位成员在一个组织里最多持有 20 把密钥（个人密钥与本人的项目密钥合计），停用和过期的也算在内，删除后才释放名额。每个项目另有最多 20 把项目服务密钥。
可用模型
每把密钥可以限定能调用的模型，最多 64 个；不限定时可以调用全部模型。在「我的密钥」打开密钥详情，在「可用模型」里选「全部模型」或「指定模型」。调用范围外的模型返回 403 model_not_allowed，/v1/models 也只列出范围内的模型。
修改带版本校验：两个人同时修改同一把密钥时，后提交的一方会收到「内容已被修改，请刷新后重试」。
有效期、停用与删除
- 有效期：新建时可选永不过期、30 天、90 天或 1 年。到期后请求返回
401，列表里显示「已过期」。 - 停用：几秒内生效，请求返回
401；之后可以重新启用。停用的密钥仍占名额。 - 删除：无法恢复，几秒内失效，同时释放名额。
需要更换密钥时，先新建一把，把调用方切换过去，再停用或删除旧的。
查看完整密钥
新建后会显示完整密钥。个人密钥和本人的项目密钥，本人之后也能在密钥详情里点「查看完整密钥」再次查看，每次查看都会记入审计；项目服务密钥只在创建时显示。
调用情况
密钥列表显示每把密钥近 7 天的调用次数。在密钥详情点「查看调用记录」，可以到「我的用量」查看这把密钥的调用。
人事变动时密钥怎么办
| 事件 | 个人密钥 | 项目服务密钥 | 登录会话 |
|---|---|---|---|
| 调到另一团队，或所在团队被删除、并入默认团队 | 跟着人迁到新团队，继续可用 | 不受影响 | 继续有效 |
| 被移出组织 | 删除，本人的项目密钥一并删除 | 不受影响 | 在该组织的会话立即结束 |
| 在飞书离职或被冻结（组织同步飞书通讯录时） | 同步后停止可用，恢复后重新可用 | 不受影响 | 同步后结束 |
调动后，个人密钥之后的用量计入新团队，之前的用量仍记在原团队。项目密钥只在本人仍直接或通过所在团队参与项目、且项目未归档时可用。
页面字体：MiSans（小米，依《MiSans 字体知识产权许可协议》使用）；Google Sans Flex（SIL Open Font License 1.1）。