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

# Authentication

> Authenticate API requests using API keys

All API requests require an API key passed in the `Authorization` header.

## Header format

```bash theme={null}
Authorization: Api-Key ak_live_your_key_here
```

## Generating API keys

1. Go to [Allo Settings > API](https://web.withallo.com/settings/api)
2. Click **Create API Key**
3. Select the scopes your integration needs
4. Copy the key — it won't be shown again

## API key scopes

Each API key has specific scopes that determine what operations it can perform.

| Scope                      | Description                                 |
| -------------------------- | ------------------------------------------- |
| `CONVERSATIONS_READ`       | Read calls, SMS, and conversation history   |
| `CONTACTS_READ`            | Read contact information                    |
| `CONTACTS_READ_WRITE`      | Read and write contact information          |
| `SMS_SEND`                 | Send SMS and MMS messages                   |
| `WEBHOOKS_READ_WRITE`      | Create and manage webhook configurations    |
| `PHONE_NUMBERS_READ`       | List phone numbers and their capabilities   |
| `USERS_READ`               | List team members and their roles           |
| `TAGS_READ`                | List available tags                         |
| `TAGS_WRITE`               | Add and remove tags on conversation items   |
| `BILLING`                  | Access billing and subscription information |
| `DIALING_QUEUE_READ_WRITE` | Manage Power Dialer queues                  |

## Scope-to-endpoint mapping

| Endpoint                                        | Method | Required scope       |
| ----------------------------------------------- | ------ | -------------------- |
| `/v2/api/conversations`                         | GET    | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/search`            | POST   | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/{id}`              | GET    | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/batch`             | POST   | `CONVERSATIONS_READ` |
| `/v2/api/conversations/{contact_number}/action` | PUT    | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/{id}/tags`         | POST   | `TAGS_WRITE`         |
| `/v2/api/conversations/items/{id}/tags/{tag}`   | DELETE | `TAGS_WRITE`         |
| `/v2/api/users`                                 | GET    | `USERS_READ`         |
| `/v2/api/users/{id}`                            | GET    | `USERS_READ`         |
| `/v2/api/tags`                                  | GET    | `TAGS_READ`          |
| `/v2/api/numbers`                               | GET    | `PHONE_NUMBERS_READ` |

## Example request

```bash theme={null}
curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_abc123def456"
```

## Error responses

**Invalid or missing key** — `401`

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "API_KEY_INVALID",
    "message": "The API key provided is invalid or has been revoked.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://help.withallo.com/en/v2/api-reference/guides/error-codes#API_KEY_INVALID"
  }
}
```

**Insufficient scope** — `403`

```json theme={null}
{
  "error": {
    "type": "permission_error",
    "code": "API_KEY_INSUFFICIENT_SCOPE",
    "message": "This API key lacks the 'CONVERSATIONS_READ' scope required for this endpoint.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "suggestion": "Create a new API key with the required scope at https://web.withallo.com/settings/api"
  }
}
```

## Security

* API keys are scoped to a single team
* Keys can be revoked at any time from settings
* Never expose keys in client-side code or public repositories
* Use environment variables to store keys in your application