# Authentification

> Authentifier les requêtes API avec des API keys

Toutes les requêtes API nécessitent une API key transmise dans le header `Authorization`.

## Format du header

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

Vous pouvez aussi envoyer la clé seule, sans préfixe :

```bash
Authorization: ak_live_your_key_here
```

<Warning>
N'envoyez pas une API key sous la forme `Bearer <votre-clé>`. Allo lit une valeur `Bearer` comme un jeton de session utilisateur, pas comme une API key : la requête renvoie `401`. Utilisez `Api-Key <votre-clé>` ou la clé seule.
</Warning>

## Générer des API keys

1. Allez dans [Paramètres Allo > API](https://web.withallo.com/settings/api)
2. Cliquez sur **Create API Key**
3. Sélectionnez les scopes dont votre intégration a besoin
4. Copiez la clé, elle ne sera plus affichée

## Scopes des API keys

Chaque API key possède des scopes spécifiques qui déterminent les opérations qu'elle peut effectuer.

| Scope | Description |
|-------|-------------|
| `CONVERSATIONS_READ` | Lire les appels, SMS et l'historique des conversations |
| `CONVERSATIONS_WRITE` | Modifier les résumés d'appel, archiver et marquer les conversations |
| `CRM_READ` | Obtenir et rechercher des personnes, entreprises et deals, et lister les champs personnalisés |
| `CRM_WRITE` | Créer et mettre à jour des personnes et des entreprises, et créer des champs personnalisés |
| `CRM_DELETE` | Supprimer des attributs personnalisés des personnes et des entreprises |
| `SMS_SEND` | Envoyer des SMS et des MMS |
| `FAX_SEND` | Envoyer des fax |
| `WEBHOOKS_READ_WRITE` | Créer et gérer les configurations de webhooks |
| `PHONE_NUMBERS_READ` | Lister les numéros de téléphone et leurs capacités |
| `PHONE_NUMBERS_WRITE` | Enregistrer et publier les call flows |
| `USERS_READ` | Lister les membres de l'équipe et leurs rôles |
| `TAGS_READ` | Lister les tags disponibles |
| `TAGS_WRITE` | Créer et supprimer des tags, les ajouter et les retirer sur les éléments de conversation |
| `NOTES_READ` | Lire les notes de conversation et les notes de personne |
| `NOTES_WRITE` | Créer, modifier et supprimer des notes |
| `THREADS_READ` | Lire les fils de discussion et leurs commentaires |
| `THREADS_WRITE` | Créer des fils et des commentaires, modifier des commentaires, résoudre des fils |
| `SUMMARY_TEMPLATES_READ` | Lire les templates de résumé d'appel de l'équipe |
| `SUMMARY_TEMPLATES_WRITE` | Créer, modifier et supprimer des templates, et définir celui par défaut d'un numéro |
| `BILLING` | Accéder aux informations de facturation et d'abonnement |
| `DIALING_QUEUE_READ_WRITE` | Gérer les files du Power Dialer |
| `AGENTS_READ` | Lire la configuration du réceptionniste IA, les agendas connectés et les voix |
| `AGENTS_WRITE` | Configurer le réceptionniste IA, son prompt, ses connaissances, et l'activer ou le désactiver |
| `INBOXES_READ` | Lister vos boîtes de réception et celles de vos coéquipiers, les suggestions de boîtes et les options du menu téléphonique d'une ligne |
| `INBOXES_WRITE` | Créer, modifier et supprimer des boîtes de réception, et couper leurs notifications |
| `PARTNER` | Créer et gérer des comptes Allo en tant que revendeur. Accordé manuellement aux revendeurs approuvés, il ne peut pas s'auto-générer |

`GET /v2/api/me` ne demande aucun scope. Toute clé valide peut l'appeler, et son tableau `endpoints` fait foi sur ce que votre clé peut atteindre.

## Correspondance scopes-endpoints

Chaque endpoint documenté et le scope dont il a besoin. Si un appel renvoie `403` avec le code `API_KEY_INSUFFICIENT_SCOPE`, la clé est valide mais il lui manque le scope indiqué ici.

**Découverte**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/v2/api/me` | GET | aucun |

**Conversations**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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 | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

**Fils de discussion**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

**Boîtes de réception**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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 | Méthode | Scope requis |
|----------|--------|---------------|
| `/v1/api/sms` | POST | `SMS_SEND` |
| `/v1/api/sms#france` | POST | `SMS_SEND` |
| `/v2/api/faxes` | POST | `FAX_SEND` |

**Numéros et call flows**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

**Réceptionniste IA**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/v2/api/calendars` | GET | `AGENTS_READ` |
| `/v2/api/calendars/{id}` | GET | `AGENTS_READ` |
| `/v2/api/voices` | GET | `AGENTS_READ` |

**Templates de résumé**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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 | Méthode | Scope requis |
|----------|--------|---------------|
| `/v2/api/tags` | GET | `TAGS_READ` |
| `/v2/api/tags` | POST | `TAGS_WRITE` |
| `/v2/api/tags/{id}` | DELETE | `TAGS_WRITE` |

**Utilisateurs**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/v2/api/users` | GET | `USERS_READ` |
| `/v2/api/users/{id}` | GET | `USERS_READ` |

**Webhooks**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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 | Méthode | Scope requis |
|----------|--------|---------------|
| `/v2/api/analytics/outbound` | POST | `CONVERSATIONS_READ` |
| `/v2/api/analytics/overview` | POST | `CONVERSATIONS_READ` |

**Files du Power Dialer**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

**Partenaires**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

**Marque blanche**

| Endpoint | Méthode | Scope requis |
|----------|--------|---------------|
| `/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` |

## Exemple de requête

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

## Réponses d'erreur

**Clé invalide ou manquante** (`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"
  }
}
```

**Scope insuffisant** (`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"
  }
}
```

## Sécurité

- Les API keys sont limitées à une seule équipe
- Les clés peuvent être révoquées à tout moment depuis les paramètres
- N'exposez jamais les clés dans du code côté client ou des dépôts publics
- Utilisez des variables d'environnement pour stocker les clés dans votre application
