# Authentication

> Authenticate API requests using API keys

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

## Header format

```bash
Authorization: Api-Key ak_live_your_key_here
```

You can also send the raw key on its own, with no prefix:

```bash
Authorization: ak_live_your_key_here
```

<Warning>
Do not send an API key as `Bearer <your-key>`. Allo reads a `Bearer` value as a user session token, not as an API key, so the request returns `401`. Use `Api-Key <your-key>` or the raw key.
</Warning>

## 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 |
| `CONVERSATIONS_WRITE` | Edit call summaries and archive or mark conversations |
| `CRM_READ` | Get and search people, companies, and deals, and list custom fields |
| `CRM_WRITE` | Create and update people and companies, and create custom fields |
| `CRM_DELETE` | Delete custom attributes on people and companies |
| `SMS_SEND` | Send SMS and MMS |
| `FAX_SEND` | Send faxes |
| `WEBHOOKS_READ_WRITE` | Create and manage webhook configurations |
| `PHONE_NUMBERS_READ` | List phone numbers and their capabilities |
| `PHONE_NUMBERS_WRITE` | Save and publish call flows |
| `USERS_READ` | List team members and their roles |
| `TAGS_READ` | List available tags |
| `TAGS_WRITE` | Create and delete tags, add and remove them on conversation items |
| `NOTES_READ` | Read conversation notes and person notes |
| `NOTES_WRITE` | Create, edit, and delete notes |
| `THREADS_READ` | Read discussion threads and their comments |
| `THREADS_WRITE` | Create threads and comments, edit comments, resolve threads |
| `SUMMARY_TEMPLATES_READ` | Read the team's call summary templates |
| `SUMMARY_TEMPLATES_WRITE` | Create, update, and delete summary templates, and set a number's default |
| `BILLING` | Access billing and subscription information |
| `DIALING_QUEUE_READ_WRITE` | Manage Power Dialer queues |
| `AGENTS_READ` | Read AI receptionist configuration, connected calendars, and voices |
| `AGENTS_WRITE` | Configure the AI receptionist, its prompt, its knowledge, and turn it on or off |
| `INBOXES_READ` | List your inboxes and teammates' inboxes, inbox suggestions, and a line's phone-menu options |
| `INBOXES_WRITE` | Create, update, mute, and delete inboxes |
| `PARTNER` | Provision and manage Allo accounts as a reseller. Granted manually to approved resellers, it cannot be self-issued |

`GET /v2/api/me` requires no scope. Any valid key can call it, and its `endpoints` array is the authoritative list of what your key can reach.

## Scope-to-endpoint mapping

Every documented endpoint and the scope it needs. If a call returns `403` with code `API_KEY_INSUFFICIENT_SCOPE`, the key is valid but missing the scope listed here.

**Discovery**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/me` | GET | none |

**Conversations**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/conversations` | GET | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/batch` | POST | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/search` | POST | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/{id}` | GET | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/{id}/recording` | GET | `CONVERSATIONS_READ` |
| `/v2/api/conversations/items/{id}/summary` | PATCH | `CONVERSATIONS_WRITE` |
| `/v2/api/conversations/items/{id}/tags` | POST | `TAGS_WRITE` |
| `/v2/api/conversations/items/{id}/tags/{tag}` | DELETE | `TAGS_WRITE` |
| `/v2/api/conversations/notes/{id}` | DELETE | `NOTES_WRITE` |
| `/v2/api/conversations/notes/{id}` | GET | `NOTES_READ` |
| `/v2/api/conversations/notes/{id}` | PATCH | `NOTES_WRITE` |
| `/v2/api/conversations/{contact_number}/action` | PUT | `CONVERSATIONS_WRITE` |
| `/v2/api/conversations/{contact_number}/notes` | GET | `NOTES_READ` |
| `/v2/api/conversations/{contact_number}/notes` | POST | `NOTES_WRITE` |
| `/v2/api/conversations/{contact_number}/pin` | DELETE | `CONVERSATIONS_WRITE` |
| `/v2/api/conversations/{contact_number}/pin` | PUT | `CONVERSATIONS_WRITE` |

**CRM**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/crm/attributes` | GET | `CRM_READ` |
| `/v2/api/crm/attributes` | POST | `CRM_WRITE` |
| `/v2/api/crm/attributes/{key}` | DELETE | `CRM_DELETE` |
| `/v2/api/crm/attributes/{key}` | PATCH | `CRM_WRITE` |
| `/v2/api/crm/companies/attributes` | GET | `CRM_READ` |
| `/v2/api/crm/companies/attributes` | POST | `CRM_WRITE` |
| `/v2/api/crm/companies/attributes/{key}` | DELETE | `CRM_DELETE` |
| `/v2/api/crm/companies/attributes/{key}` | PATCH | `CRM_WRITE` |
| `/v2/api/crm/companies` | POST | `CRM_WRITE` |
| `/v2/api/crm/companies/search` | POST | `CRM_READ` |
| `/v2/api/crm/companies/{id}` | GET | `CRM_READ` |
| `/v2/api/crm/companies/{id}` | PUT | `CRM_WRITE` |
| `/v2/api/crm/deals/search` | POST | `CRM_READ` |
| `/v2/api/crm/deals/{id}` | GET | `CRM_READ` |
| `/v2/api/crm/people` | POST | `CRM_WRITE` |
| `/v2/api/crm/people/search` | POST | `CRM_READ` |
| `/v2/api/crm/people/{id}` | GET | `CRM_READ` |
| `/v2/api/crm/people/{id}` | PUT | `CRM_WRITE` |
| `/v2/api/crm/people/{person_id}/notes` | GET | `NOTES_READ` |
| `/v2/api/crm/people/{person_id}/notes` | POST | `NOTES_WRITE` |
| `/v2/api/crm/people/{person_id}/notes/{note_id}` | DELETE | `NOTES_WRITE` |
| `/v2/api/crm/people/{person_id}/notes/{note_id}` | PATCH | `NOTES_WRITE` |

**Threads**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/threads` | GET | `THREADS_READ` |
| `/v2/api/threads` | POST | `THREADS_WRITE` |
| `/v2/api/threads/comments/{comment_id}` | PATCH | `THREADS_WRITE` |
| `/v2/api/threads/{id}` | GET | `THREADS_READ` |
| `/v2/api/threads/{id}/comments` | POST | `THREADS_WRITE` |
| `/v2/api/threads/{id}/resolve` | POST | `THREADS_WRITE` |
| `/v2/api/threads/{id}/unresolve` | POST | `THREADS_WRITE` |

**Inboxes**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/inboxes` | GET | `INBOXES_READ` |
| `/v2/api/inboxes` | POST | `INBOXES_WRITE` |
| `/v2/api/inboxes/suggestions` | GET | `INBOXES_READ` |
| `/v2/api/inboxes/{inbox_id}` | DELETE | `INBOXES_WRITE` |
| `/v2/api/inboxes/{inbox_id}` | PATCH | `INBOXES_WRITE` |
| `/v2/api/numbers/{number}/menu_options` | GET | `INBOXES_READ` |

**SMS**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v1/api/sms` | POST | `SMS_SEND` |
| `/v1/api/sms#france` | POST | `SMS_SEND` |
| `/v2/api/faxes` | POST | `FAX_SEND` |

**Phone numbers and call flows**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/numbers` | GET | `PHONE_NUMBERS_READ` |
| `/v2/api/numbers/{number}/agent` | GET | `AGENTS_READ` |
| `/v2/api/numbers/{number}/agent` | PATCH | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/knowledge/files/{id}` | DELETE | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/knowledge/websites` | POST | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/knowledge/websites/{id}` | DELETE | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/knowledge/websites/{id}` | PATCH | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/prompt` | PUT | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/agent/status` | PUT | `AGENTS_WRITE` |
| `/v2/api/numbers/{number}/call_flow` | GET | `PHONE_NUMBERS_READ` |
| `/v2/api/numbers/{number}/call_flow/draft` | GET | `PHONE_NUMBERS_READ` |
| `/v2/api/numbers/{number}/call_flow/draft` | PUT | `PHONE_NUMBERS_WRITE` |
| `/v2/api/numbers/{number}/call_flow/publish` | POST | `PHONE_NUMBERS_WRITE` |
| `/v2/api/numbers/{number}/default_summary_template` | PUT | `SUMMARY_TEMPLATES_WRITE` |

**AI receptionist**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/calendars` | GET | `AGENTS_READ` |
| `/v2/api/calendars/{id}` | GET | `AGENTS_READ` |
| `/v2/api/voices` | GET | `AGENTS_READ` |

**Summary templates**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/summary_templates` | GET | `SUMMARY_TEMPLATES_READ` |
| `/v2/api/summary_templates` | POST | `SUMMARY_TEMPLATES_WRITE` |
| `/v2/api/summary_templates/{id}` | DELETE | `SUMMARY_TEMPLATES_WRITE` |
| `/v2/api/summary_templates/{id}` | GET | `SUMMARY_TEMPLATES_READ` |
| `/v2/api/summary_templates/{id}` | PUT | `SUMMARY_TEMPLATES_WRITE` |

**Tags**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/tags` | GET | `TAGS_READ` |
| `/v2/api/tags` | POST | `TAGS_WRITE` |
| `/v2/api/tags/{id}` | DELETE | `TAGS_WRITE` |

**Users**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/users` | GET | `USERS_READ` |
| `/v2/api/users/{id}` | GET | `USERS_READ` |

**Webhooks**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/webhooks` | GET | `WEBHOOKS_READ_WRITE` |
| `/v2/api/webhooks` | POST | `WEBHOOKS_READ_WRITE` |
| `/v2/api/webhooks/event_types` | GET | `WEBHOOKS_READ_WRITE` |
| `/v2/api/webhooks/{webhook_id}` | DELETE | `WEBHOOKS_READ_WRITE` |
| `/v2/api/webhooks/{webhook_id}` | GET | `WEBHOOKS_READ_WRITE` |
| `/v2/api/webhooks/{webhook_id}` | PUT | `WEBHOOKS_READ_WRITE` |

**Analytics**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/analytics/outbound` | POST | `CONVERSATIONS_READ` |
| `/v2/api/analytics/overview` | POST | `CONVERSATIONS_READ` |

**Dialing queues**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/dialing-queues/current` | GET | `DIALING_QUEUE_READ_WRITE` |
| `/v2/api/dialing-queues/current` | PATCH | `DIALING_QUEUE_READ_WRITE` |
| `/v2/api/dialing-queues/current` | POST | `DIALING_QUEUE_READ_WRITE` |
| `/v2/api/dialing-queues/current/numbers` | DELETE | `DIALING_QUEUE_READ_WRITE` |
| `/v2/api/dialing-queues/current/numbers` | POST | `DIALING_QUEUE_READ_WRITE` |

**Partners**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/partner/accounts` | POST | `PARTNER` |
| `/v2/api/partner/accounts/price` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{id}` | DELETE | `PARTNER` |
| `/v2/api/partner/accounts/{id}` | GET | `PARTNER` |
| `/v2/api/partner/credit` | GET | `PARTNER` |

**White label**

| Endpoint | Method | Required scope |
|----------|--------|---------------|
| `/v2/api/partner/accounts/{account_id}/esims` | POST | `PARTNER` |
| `/v2/api/partner/accounts/{account_id}/esims/offer` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{account_id}/sender_ids` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{account_id}/sender_ids` | POST | `PARTNER` |
| `/v2/api/partner/accounts/{account_id}/sender_ids/{id}` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{id}/members` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{id}/members` | POST | `PARTNER` |
| `/v2/api/partner/accounts/{id}/members/{member_id}` | DELETE | `PARTNER` |
| `/v2/api/partner/accounts/{id}/numbers` | POST | `PARTNER` |
| `/v2/api/partner/accounts/{id}/numbers/price` | GET | `PARTNER` |
| `/v2/api/partner/accounts/{id}/resume` | POST | `PARTNER` |
| `/v2/api/partner/accounts/{id}/suspend` | POST | `PARTNER` |
| `/v2/api/partner/esims/{id}` | GET | `PARTNER` |
| `/v2/api/partner/esims/{id}/activation_code` | GET | `PARTNER` |
| `/v2/api/partner/esims/{id}/revoke` | POST | `PARTNER` |
| `/v2/api/partner/esims/{id}/tier` | PUT | `PARTNER` |
| `/v2/api/partner/esims/{id}/topups` | POST | `PARTNER` |

## Example request

```bash
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
{
  "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://www.withallo.com/docs/guides/error-codes#api_key_invalid"
  }
}
```

**Insufficient scope** (`403`)
```json
{
  "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
