Authentication & authorization

API keys

Every request must include your secret key. Two header forms are accepted:

Authorization: Bearer zt_live_sk_...

x-api-key: zt_live_sk_...

Keys are:

Environment-scoped - zt_live_* and zt_test_* access separate data.
Hashed at rest - only a SHA-256 hash is stored; the plaintext secret is
shown once at creation.
Scoped - each key carries a set of scopes. Requests without the required
scope return 403 insufficient_scope.

Scope	Grants
`clips:read`	List/read clips, export JSON
`clips:write`	Trigger clip generation
`highlights:read`	List/read highlights
`highlights:write`	Trigger highlight generation
`media:read`	Read media library and delivery URLs
`publish:read`	Read publish history
`publish:write`	Publish clips
`storage:write`	Push clips to external storage
`webhooks:manage`	Manage webhook endpoints
`catalog:read`	Read competitions, teams, players, tags, streams

Rotate a key to mint a replacement while the old key stays valid for a
short grace window (default 24h), then revoke it.
Revoke a key immediately to disable it.

For high-trust partners, an app can restrict requests to specific source IPs or
CIDR ranges. Requests from other IPs return 403 ip_not_allowed.

All requests must use HTTPS. Never embed secret keys in client-side code.