> ## 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 |
| `CONVERSATIONS_WRITE` | Edit call summaries and archive or mark conversations |
| `CRM_READ` | Get and search people, companies, and deals |
| `CRM_WRITE` | Create and update people and companies |
| `SMS_SEND` | Send SMS and MMS messages |
| `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 |
| `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}/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` |

**CRM**

| Endpoint | Method | Required scope |
| - | - | - |
| `/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` |

**SMS**

| Endpoint | Method | Required scope |
| - | - | - |
| `/v1/api/sms` | POST | `SMS_SEND` |
| `/v1/api/sms#france` | POST | `SMS_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` |

**Partner**

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

## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.