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

# API Keys & Authentication

> Generate, use, and manage the API keys that authenticate requests to the Voxworks API, plus the exact error responses to expect.

## What are API Keys?

Every request to the Voxworks API authenticates with an API key sent as a Bearer token. Keys are generated and managed from **Settings > API Keys** inside your team account, and every key belongs to the team it was created in — there's no per-user or personal key.

***

## Generating a key

1. Go to **Settings > API Keys**.
2. Click **Generate Key**.
3. Optionally give it a name in the **Key Name (optional)** field — for example, `Monday.com Production` — so you can tell keys apart later. If you leave it blank, the key is named `Default`.
4. Click **Generate**.

The full key is shown once, with this notice:

> Copy your API key now. It won't be shown again.

Copy it immediately and store it somewhere safe (a secrets manager or password vault). Voxworks stores only a hash of the key, not the plaintext, so support can't retrieve a lost key for you — you'll need to revoke it and generate a new one.

### Key format

Keys are prefixed `vxw_`, followed by a random token, for example:

```text theme={null}
vxw_Q3oV0xsz2mrPEjsjCOb7b8AuxBS3f4pd1gPXaNUhHig
```

The **API Keys** list shows only the prefix (the `vxw_` plus the first few characters) as a badge next to each key's name — the rest is never displayed again after creation.

***

## Using the key

Send the key as a Bearer token in the `Authorization` header of every request:

```http theme={null}
Authorization: Bearer vxw_Q3oV0xsz2mrPEjsjCOb7b8AuxBS3f4pd1gPXaNUhHig
```

```bash theme={null}
curl https://api.voxworks.ai/api/v1/calls \
  -H "Authorization: Bearer vxw_Q3oV0xsz2mrPEjsjCOb7b8AuxBS3f4pd1gPXaNUhHig"
```

Every endpoint in the API reference requires this header except the health check, which is unauthenticated, and inbound automation webhooks, which authenticate with a webhook token in the URL instead of a Bearer key.

***

## Team scoping

An API key is scoped to the team it was generated in. Every resource the key can read or write — calls, contacts, lists, custom variables — is filtered to that team automatically; there's no separate account or team ID to pass in the request. If you work across multiple teams, generate a separate key in each one. See [Roles & Permissions](/team/roles-permissions) for how team membership itself is managed.

***

## Managing keys

The **API Keys** table lists each key's name, prefix badge, creation date, and last-used date (shown as "Never" if the key hasn't authenticated a request yet). From here you can:

* **Revoke a key** — click the delete icon next to it. Revoking is immediate and permanent: any request using that key starts failing right away, and the key drops off the list entirely.
* **Generate a new key** — click **Generate Key** at any time; there's no limit enforced in the UI on how many active keys a team can hold.

There's no separate "rotate" action. To rotate a key, generate the replacement first, update it in whatever system calls the API, confirm it works, then revoke the old key.

***

## Authentication errors

Requests that fail authentication get a JSON body in the standard error shape:

```json theme={null}
{
  "success": false,
  "message": "Invalid API key"
}
```

### 401 Unauthorized

Returned when the request has no usable credentials.

| Scenario                                                      | `message`                                   |
| ------------------------------------------------------------- | ------------------------------------------- |
| No `Authorization` header, or it doesn't start with `Bearer ` | `Missing or malformed Authorization header` |
| `Authorization: Bearer ` sent with nothing after it           | `API key is empty`                          |
| Key doesn't match any key on record                           | `Invalid API key`                           |
| Key lookup failed unexpectedly                                | `Authentication failed`                     |

### 403 Forbidden

Returned when the credentials are well-formed and recognised, but the key itself is no longer usable.

| Scenario             | `message`                  |
| -------------------- | -------------------------- |
| Key has been revoked | `API key has been revoked` |

Once a request authenticates, it's still subject to per-key and per-team rate limits — see [Rate Limits & Request Limits](/api-reference/rate-limits) for the exact buckets and the `429` response shape.

***

## Next Steps

* [API Overview](/api-reference/overview) — base URL, request/response conventions, and general error handling.
* [API Quickstart](/api-reference/quickstart) — generate a key and make your first request end to end.
* [Rate Limits & Request Limits](/api-reference/rate-limits) — every rate-limit bucket and the `429` response headers.
* [Roles & Permissions](/team/roles-permissions) — how team membership and access work alongside API keys.