跳到主要内容

鉴权与 Scopes

C2AI2X 当前对外入口并不是匿名入口。

1. 当前鉴权 contract​

当前 POST /api/execute 的 live contract 为：

  • x-zhen-contract-auth: admin_or_api_key
  • security: bearerAuth

因此，外部接入方当前应使用平台签发的 Bearer 凭证访问该路由。

当前 actor 边界还包括：

  • api_key bearer 可以直接调用该路由，key_id 由 bearer 解析
  • admin bearer 当前必须在 body 中显式提供 key_id
  • session bearer 当前不是这条路由的 live auth 模式

2. required_scopes 的作用​

请求体中的 required_scopes 用于表达调用方希望本次执行至少满足哪些 scope。

平台会基于已绑定的 key / actor / org 上下文做 admission：

  • 若 scope 不满足，平台拒绝进入执行面
  • 若 entitlement 不满足，平台拒绝进入执行面
  • 若 quota 不满足，平台拒绝进入执行面

这意味着：

  • 调用方可以声明 required_scopes
  • 但最终解释权不在调用方，而在平台

3. 授权真相边界​

即使调用方在 structured_input 中携带 neutral AuthorizationGrant 对象，以下事实仍由平台掌握：

  • API key 是否有效
  • key 属于哪个 org / workspace / actor
  • scopes 是否满足
  • entitlements 是否满足
  • quota 是否充足
  • sandbox 如何构造

zhen-brain-core 不接管这些真相。

4. 实践建议​

  • 为每个接入方发独立 API key 或明确 Bearer 身份
  • 把接入所需 scopes 显式写入 required_scopes
  • 不要把 AuthorizationGrant 当成绕过平台 admission 的手段
  • 不要让前台站点或插件直连 brain