鉴权与权限
所有 /v1 接口都要求请求头：
Authorization: Bearer zsk_...- 一个凭据对应一个固定的调用方
caller_id和一组权限。请求中的任何字段都不能声明或修改调用方。 - 服务端只保存凭据的 SHA-256 摘要，凭据丢失后无法找回，只能重新发放。
- 服务只面向服务端调用：没有 CORS 策略，浏览器无法直接调用。MCP 接口会拒绝任何带
Origin头的请求（403）。
| 权限 | 用途 |
|---|---|
services:read |
读取能力目录 GET /v1/services |
executions:read |
读取自己的调用日志 GET /v1/executions* |
<capability>:<operation> |
调用某个能力，例如 public_holiday:query、scholarly_search:search |
每个能力需要的权限写在能力参考的对应页面上。能力目录和 MCP 工具列表只会出现你有权限的能力。
外部与内部调用方
Section titled “外部与内部调用方”数据源有准入级别。外部调用方只能看到并使用准入级别为 production 的数据源；内部调用方还可以使用正在验证的数据源，用于测试。本文档的能力参考以外部调用方的视角编写。
| 状态 | error_code |
含义 |
|---|---|---|
| 401 | AUTH.UNAUTHORIZED |
没有凭据或凭据无效 |
| 403 | AUTH.FORBIDDEN |
凭据有效，但缺少该接口的权限 |
一个调用方可以同时拥有多个有效凭据。轮换时先申请新凭据并完成切换，再通知 ZGI 平台团队吊销旧凭据，整个过程不需要停机。怀疑泄露时请立即联系平台团队吊销。