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

# Authentication

All API endpoints require authentication using API Keys. To authenticate your requests:

## API Keys

1. Obtain your API Key from the [API Integration Settings](https://eu.volubile.ai/integrations/api) page.
2. Include this key in the `X-Api-Key` header of your HTTP request:

```
X-Api-Key: {volubile-api-key}
```

### API Key Rotation

Volubile provides a pair of API keys enabling you to manage a regular rotation or replace a potentially compromised key.

## Bearer Tokens

Volubile also provides short-lived JWT Bearer tokens.

This flow is useful when you do not want to expose your API key to downstream services and when you want to limit the permissions granted to a client with scoped access.

### Issue a token

Use your API key to request a Bearer token from [`POST /v1/auth/token`](/api-reference/auth/create-token).

For the full request and response reference, see [Create Token](/api-reference/auth/create-token).

#### Supported scopes

##### Agents

| Method                                                     | Route                                | Scope                     |
| ---------------------------------------------------------- | ------------------------------------ | ------------------------- |
| <Badge color="green" shape="pill" size="xs">GET</Badge>    | <code>/v1/agents</code>              | <code>agents:read</code>  |
| <Badge color="green" shape="pill" size="xs">GET</Badge>    | <code>/v1/agents/{'{'}id{'}'}</code> | <code>agents:read</code>  |
| <Badge color="yellow" shape="pill" size="xs">PATCH</Badge> | <code>/v1/agents/{'{'}id{'}'}</code> | <code>agents:write</code> |

##### Calls

| Method                                                  | Route                                          | Scope                    |
| ------------------------------------------------------- | ---------------------------------------------- | ------------------------ |
| <Badge color="green" shape="pill" size="xs">GET</Badge> | <code>/v1/calls</code>                         | <code>calls:read</code>  |
| <Badge color="green" shape="pill" size="xs">GET</Badge> | <code>/v1/calls/{'{'}id{'}'}</code>            | <code>calls:read</code>  |
| <Badge color="blue" shape="pill" size="xs">POST</Badge> | <code>/v1/calls</code>                         | <code>calls:write</code> |
| <Badge color="green" shape="pill" size="xs">GET</Badge> | <code>/v1/calls/{'{'}id{'}'}/recording</code>  | <code>calls:read</code>  |
| <Badge color="green" shape="pill" size="xs">GET</Badge> | <code>/v1/calls/{'{'}id{'}'}/transcript</code> | <code>calls:read</code>  |

##### Campaigns

| Method                                                  | Route                                          | Scope                        |
| ------------------------------------------------------- | ---------------------------------------------- | ---------------------------- |
| <Badge color="green" shape="pill" size="xs">GET</Badge> | <code>/v1/campaigns/{'{'}id{'}'}</code>        | <code>campaigns:read</code>  |
| <Badge color="blue" shape="pill" size="xs">POST</Badge> | <code>/v1/campaigns</code>                     | <code>campaigns:write</code> |
| <Badge color="blue" shape="pill" size="xs">POST</Badge> | <code>/v1/campaigns/{'{'}id{'}'}/status</code> | <code>campaigns:write</code> |

##### Bulk

| Method                                                  | Route                       | Scope                    |
| ------------------------------------------------------- | --------------------------- | ------------------------ |
| <Badge color="blue" shape="pill" size="xs">POST</Badge> | <code>/v1/bulk/calls</code> | <code>calls:write</code> |

### Use a Bearer token

Send the issued token in the `Authorization` header:

```http theme={null}
Authorization: Bearer {jwt-bearer-token}
```

Bearer tokens are short lived and scoped to the permissions requested when they are issued.

<Warning>
  Bearer tokens cannot be used to mint another token. Only API keys can call [`POST /v1/auth/token`](/api-reference/auth/create-token).
</Warning>