认证与鉴权

OpenAPI 接口（/v1/openapi/*）使用 API Key 鉴权，只需携带以下请求头：

Authorization: Bearer sk_***

Authorization 必须是 Bearer <api_key> 格式，api_key 形如 sk_*。

WARNING

sk_* 仅用于服务端调用。不要放在前端代码、浏览器本地存储或公开仓库中。

API Key 与工作空间的关系

每个 API Key 在创建时就绑定到一个工作空间，只能访问该工作空间下的资源。网关校验 API Key 后会自动识别并注入可信的工作空间上下文，调用方无需传入工作空间请求头。

在 平台所在工作空间的 基础服务 → 开发管理 → 密钥管理 创建或获取 API Key：

https://runtime-platform.invalid/base/developer-manage/key-manage

创建前请确认页面顶部选择的是目标工作空间。该页面支持创建、查看和禁用 API Key。

调用示例

curl -X POST "https://runtime-api.invalid/v1/openapi/chat/send-messages" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

校验规则（与网关实现一致）

网关会按以下顺序处理：

1. 检查 Authorization 是否存在
2. 检查是否满足 Bearer <token> 格式
3. 通过鉴权服务校验 API Key 是否有效、是否禁用、是否过期
4. 根据 API Key 获取其绑定的工作空间，并向后端服务注入可信的工作空间上下文

鉴权失败时，网关会直接拒绝请求。

常见错误与排查

HTTP 状态码	错误信息（示例）	含义	处理建议
401	缺少 API Key / 缺少认证信息	未传 Authorization	补充 Authorization: Bearer sk_*
401	认证格式错误	Authorization 不是 Bearer ... 格式	检查是否遗漏 Bearer 前缀
401	invalid api key	API Key 不存在或非法	检查 Key 是否正确、是否被截断
401	api key disabled	API Key 已禁用	在管理后台启用或重新创建
401	api key expired	API Key 已过期	重新生成 API Key

鉴权字段说明

Header	必填	示例	说明
Authorization	是	Bearer sk_xxx	OpenAPI 的访问凭证；网关据此识别工作空间

与控制台登录态的区别

• OpenAPI：使用 sk_* API Key
• 控制台/后台接口：通常使用登录 Token（JWT）体系

如果你接入的是第三方 OpenAPI，请优先使用本文档的 API Key 方案。