> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Scoped API keys, and how to rotate them without downtime.

Send your key as a bearer token:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/agents \
  -H "Authorization: Bearer wv_live_…"
```

## Scopes

Keys are scoped. Grant an integration only what it needs — a key that reads call
logs cannot place calls.

<Note>
  There is no admin scope, and one cannot be created. Anything an administrator can
  do is unreachable from an API key by construction, not by a permission check that
  could be misconfigured.
</Note>

| Scope                                | Grants                          |
| ------------------------------------ | ------------------------------- |
| `agents:read` / `agents:write`       | Agent configuration             |
| `calls:read` / `calls:write`         | Reading calls, and placing them |
| `leads:read` / `leads:write`         | Contacts and merge-field data   |
| `campaigns:read` / `campaigns:write` | Bulk calling                    |
| `usage:read`                         | Itemised billing lines          |
| `billing:read`                       | Balance, ledger and top-ups     |

A key cannot create another key with scopes it does not itself hold — otherwise a
narrow key would be a privilege-escalation step rather than a limit.

## Live and test keys

Keys carry a `wv_live_` or `wv_test_` prefix, so a test key pasted into
production fails loudly instead of quietly operating on real data.

## Rotation

`POST /v1/api-keys/{id}/rotate` issues a replacement and keeps the old key
working for **24 hours**. A deploy is never caught in a window where neither key
is valid.

Revocation (`DELETE`) is immediate, with no grace — that is what you reach for
when a key has leaked.

## Versioning

The `/v1` prefix covers additive changes. Anything that changes behaviour ships
behind a dated `Wixzel-Version` header, and an existing key keeps the behaviour
it was created with.

```bash theme={null}
-H "Wixzel-Version: 2026-09-01"
```