Authentication
Service credentials
Section titled “Service credentials”Every /v1 route requires:
Authorization: Bearer zsk_...- A credential maps to one stable
caller_idand a scope set. No request field can declare or override the caller. - Services stores only a SHA-256 digest of the credential. A lost credential cannot be recovered, only replaced.
- Services is for server-side callers: there is no CORS policy, and the MCP endpoint refuses any request with an
Originheader (403).
Scopes
Section titled “Scopes”| Scope | Grants |
|---|---|
services:read |
The capability catalog, GET /v1/services |
executions:read |
Your own call log, GET /v1/executions* |
<capability>:<operation> |
Calling a capability, for example public_holiday:query or scholarly_search:search |
Each capability page lists the scope it needs. The catalog and the MCP tool list show only capabilities you are scoped for.
External and internal callers
Section titled “External and internal callers”Providers have an admission level. External callers see and use providers admitted to production only; internal callers can also use providers still being validated, for testing. This reference is written from an external caller’s view.
Telling errors apart
Section titled “Telling errors apart”| Status | error_code |
Meaning |
|---|---|---|
| 401 | AUTH.UNAUTHORIZED |
Missing or invalid credential |
| 403 | AUTH.FORBIDDEN |
Valid credential without the route’s scope |
Keeping and rotating credentials
Section titled “Keeping and rotating credentials”A caller can hold several valid credentials at once. To rotate, obtain a new credential, switch over, then ask the ZGI platform team to revoke the old one; nothing has to stop. If a credential may have leaked, ask for revocation immediately.