---
updatedAt: 2026-07-01T18:33:41.000Z
---

Fetch the complete documentation index at: https://developers.zentag.ai/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Authentication & authorization

How to authenticate requests with API keys and scope your access.

## API keys

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

```http
Authorization: Bearer zt_live_sk_...
```
```http
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`.

## Scopes

| 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 |

## Rotation & revocation

* **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.

## IP allowlisting (optional)

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`.

## Transport security

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