受控开放
Base URL 与白名单端点可验证；API Key 与生产权限仍通过开通流程发放。本文档用于集成预览，不等价于匿名自助开放。
Full API 不是匿名调用：你需要一个平台签发的 Bearer 凭证，并在请求中声明本次执行最少需要的 scopes（required_scopes）。
本页用于接入设计与实现校准：告诉你该怎么写、该怎么理解拒绝原因、以及如何把权限边界固化成可审计的规则。
凭证有效
平台签发的 Bearer 必须可被识别且处于有效状态。
未通过：先确认凭证与组织配置。scope 足够
required_scopes 必须准确表达本次执行所需的最小能力。
未通过：收窄或修正所需 scope，不扩大请求体。entitlement 与 quota 允许
组织级资格和当前容量必须允许本次执行。
未通过：通过正式平台流程核对资格与容量边界。
任何一层未通过，请先修正权限配置，不要通过扩大请求体来绕过校验。
1. 目标鉴权 contract
当前 POST /api/execute 的鉴权方式为 Bearer（以 OpenAPI 为准）：
x-zhen-contract-auth: admin_or_api_keysecurity: bearerAuth
你会遇到两类常见 Bearer：
api_key：面向集成方的凭证（通常不需要你在 body 再重复提交key_id）admin：管理侧凭证（当前请求形态可能要求你在 body 显式带key_id）
2. required_scopes 的作用
required_scopes 用于表达：这次执行需要哪些最小能力。它是一个显式的安全边界，帮助你在代码、审计与评审中“把权限说清楚”。
平台会根据你的凭证与组织权限判断是否允许执行：
- scope 不满足：直接拒绝
- entitlement 不满足：直接拒绝
- quota 不足：直接拒绝
你可以声明 required_scopes，但最终能不能执行，以平台的判定为准。
提示关于授权对象：只作为上下文携带，不替代平台判定
你可以把协议层的 AuthorizationGrant 放进 structured_input，用于表达你的业务授权语义；但它不会绕过平台对凭证、scope、entitlement 和 quota 的校验。
3. 实践建议
- 为每个集成方使用独立的凭证与最小权限集合（便于审计与撤销）。
- 把你真正需要的 scopes 固化到
required_scopes，不要“默认给全量”。 - 如果你有多条业务链路（例如不同产品线/站点/入口），把 scopes 分组，避免一个 key 承载所有权限。
推荐阅读
继续往下读
按这个顺序读，能更快把权限、请求与错误处理串起来。