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

# Authentification

> Authentifier les requetes API avec des API keys

Toutes les requetes API necessitent une API key transmise dans le header `Authorization`.

## Format du header

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

## Generer des API keys

1. Allez dans [Parametres Allo > API](https://web.withallo.com/settings/api)
2. Cliquez sur **Create API Key**
3. Selectionnez les scopes dont votre integration a besoin
4. Copiez la cle — elle ne sera plus affichee

## Scopes des API keys

Chaque API key possede des scopes specifiques qui determinent les operations qu'elle peut effectuer.

| Scope                      | Description                                                    |
| -------------------------- | -------------------------------------------------------------- |
| `CONVERSATIONS_READ`       | Lire les appels, SMS et l'historique des conversations         |
| `CONTACTS_READ`            | Lire les informations de contact                               |
| `CONTACTS_READ_WRITE`      | Lire et modifier les informations de contact                   |
| `SMS_SEND`                 | Envoyer des SMS et MMS                                         |
| `WEBHOOKS_READ_WRITE`      | Creer et gerer les configurations de webhooks                  |
| `PHONE_NUMBERS_READ`       | Lister les numeros de telephone et leurs capacites             |
| `USERS_READ`               | Lister les membres de l'equipe et leurs roles                  |
| `TAGS_READ`                | Lister les tags disponibles                                    |
| `TAGS_WRITE`               | Ajouter et supprimer des tags sur les elements de conversation |
| `BILLING`                  | Acceder aux informations de facturation et d'abonnement        |
| `DIALING_QUEUE_READ_WRITE` | Gerer les files d'attente de composition                       |

## Correspondance scopes-endpoints

| Endpoint                                        | Methode | Scope requis         |
| ----------------------------------------------- | ------- | -------------------- |
| `/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` |

## Exemple de requete

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

## Reponses d'erreur

**Cle invalide ou manquante** — `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"
  }
}
```

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

## Securite

* Les API keys sont limitees a une seule equipe
* Les cles peuvent etre revoquees a tout moment depuis les parametres
* N'exposez jamais les cles dans du code cote client ou des depots publics
* Utilisez des variables d'environnement pour stocker les cles dans votre application