Cube Sandbox

简体中文

English

简体中文

English

Appearance

API 鉴权说明 ​

Cube Sandbox 的 API 鉴权机制同时面向两类调用方：

  • 应用 / SDK 调用方：通常走 Authorization: Bearer
  • Dashboard / 管理调用方：通常走 X-API-Key

两种方式都可以被转发给鉴权回调服务，由回调方做最终放行决策。

工作原理 ​

当启用了鉴权回调后，请求会按下面的逻辑处理：

  1. 服务端优先读取 Authorization: Bearer
  2. 如果没有 Bearer，再读取 X-API-Key
  3. 将凭证和原始请求路径透传给鉴权回调服务
  4. 回调返回 200 时放行，其他状态码返回未授权

这意味着：

  • 鉴权决策不在 Cube Sandbox 内部硬编码
  • Bearer 与 API Key 都只是“凭证载体”
  • 真正的权限模型由你的鉴权服务决定

Bearer 与 X-API-Key 的使用场景 ​

Authorization: Bearer ​

更适合：

  • E2B SDK
  • 应用代码直接请求兼容 API
  • 已有认证体系统一使用 Bearer Token 的场景

X-API-Key ​

更适合：

  • Web Dashboard
  • 内部管理工具
  • 轻量运维脚本

Web Dashboard 的本地 Key 模式 ​

Web Dashboard 的前端会从浏览器本地读取已保存的 API Key，并在请求 /cubeapi/v1/* 时自动带上 X-API-Key。

这意味着：

  • Dashboard 是否能正常操作，不只取决于 UI 是否能打开
  • 还取决于当前本地保存的 Key 是否有效
  • 当 Dashboard 操作失败时，应同时检查连通性、鉴权是否开启、以及当前 Key 是否正确

建议配合阅读：

E2B SDK 的 Bearer 模式 ​

E2B SDK 会把 E2B_API_KEY 作为 Bearer Token 自动附加到请求头中。这也是为什么很多应用接入只需要设置：

  • E2B_API_URL
  • E2B_API_KEY

如果你使用的是 Cube Sandbox 的兼容入口，而不是 Dashboard 管理面，这通常是更自然的方式。

继续阅读：

常见错误与状态码 ​

场景常见表现
未携带凭证401 Unauthorized
回调显式拒绝401 Unauthorized
回调服务不可达500 Internal Server Error
Dashboard 打得开但操作失败常见于本地 Key 无效、鉴权开启但未配置正确

安全建议 ​

  • 不要把生产环境 API Key 直接写死在公开前端代码中
  • 尽量让回调服务根据路径区分管理 API 与业务 API 的权限范围
  • 对高风险接口增加更细粒度的授权策略和审计能力
  • 将 Dashboard 使用的管理 Key 与应用使用的 SDK Key 分开管理

相关文档 ​