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

# Clés API et permissions

> Comprenez l’authentification, le périmètre des clés et les permissions de l’API Chataigne.

Chaque requête à l’API Chataigne doit inclure une clé API Chataigne dans l’en-tête `x-api-key`.

```bash theme={null}
curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: ch_org_..."
```

Les clés commencent par `ch_org_`. Ce préfixe identifie le type d’identifiant ; la valeur complète est secrète.

<Warning>
  Conservez les clés API sur les serveurs que vous contrôlez. Ne les intégrez pas dans un site web ou une application mobile, ne les enregistrez pas dans le contrôle de version et ne les écrivez pas dans les journaux. Stockez-les dans une variable d’environnement ou un gestionnaire de secrets, et renouvelez-les en cas d’exposition.
</Warning>

## Périmètre et permissions

Les accès sont contrôlés par deux règles indépendantes :

* Le **périmètre** détermine les organisations ou établissements que la clé peut atteindre.
* Les **permissions** déterminent les actions que la clé peut effectuer sur ces ressources.

Une requête réussit uniquement si la ressource est dans le périmètre de la clé **et** si celle-ci possède la permission requise par l’endpoint.

### Clés limitées à une organisation commerciale

Une clé limitée à une organisation commerciale peut atteindre cette organisation et ses établissements enfants. Par exemple :

* `GET /v1/organizations` renvoie l’organisation.
* `GET /v1/locations` renvoie les établissements accessibles de l’organisation.
* Une requête visant un établissement extérieur à l’organisation est rejetée.

### Clés limitées à un établissement

Une clé limitée à un établissement peut atteindre uniquement cet établissement. Elle ne peut pas accéder à l’organisation parente ni à un autre établissement. Par exemple :

* `GET /v1/locations` renvoie l’établissement de la clé.
* `GET /v1/organizations` renvoie une liste vide.
* Une requête visant un établissement voisin est rejetée.

<Note>
  Un établissement autonome n’a pas d’organisation parente. Une clé limitée à un établissement fonctionne de la même façon, que celui-ci appartienne ou non à une organisation.
</Note>

## Permissions courantes

Les permissions suivent la forme `ressource.action`. Votre contact Chataigne les configure lors de l’émission de la clé.

| Permission                                                     | Autorise à                                                           |
| -------------------------------------------------------------- | -------------------------------------------------------------------- |
| `businessOrganization.read`                                    | Lister et récupérer l’organisation commerciale dans le périmètre.    |
| `businessOrganization.update`                                  | Mettre à jour le profil de l’organisation commerciale.               |
| `location.read`                                                | Lister et récupérer les établissements dans le périmètre.            |
| `location.create`                                              | Créer un établissement dans l’organisation commerciale du périmètre. |
| `location.update`                                              | Mettre à jour le profil d’un établissement.                          |
| `orderSettings.read` / `orderSettings.write`                   | Lire ou modifier les paramètres de commande.                         |
| `openingHoursSettings.read` / `openingHoursSettings.write`     | Lire ou modifier les horaires et fermetures exceptionnelles.         |
| `deliverySettings.read` / `deliverySettings.write`             | Lire ou modifier les paramètres de livraison.                        |
| `locationStatusSettings.read` / `locationStatusSettings.write` | Lire ou modifier l’acceptation des commandes.                        |
| `ai.read` / `ai.write`                                         | Lire ou modifier les instructions du commis IA.                      |
| `analytics.read`                                               | Récupérer les données analytiques.                                   |

Accordez uniquement les permissions nécessaires à votre intégration. Une intégration de reporting en lecture seule, par exemple, n’a besoin d’aucune permission `write`, `update` ou `create`.

## Erreurs d’authentification

| Statut                     | Signification                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `401 authentication_error` | L’en-tête `x-api-key` est absent ou la clé est mal formée, expirée ou invalide.       |
| `403 authorization_error`  | La clé est valide, mais son périmètre ou ses permissions n’autorisent pas la requête. |
| `404 not_found_error`      | La ressource demandée n’existe pas ou n’est pas disponible pour la clé.               |

Le corps de l’erreur contient un identifiant de requête :

```json theme={null}
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permission",
    "message": "This API key does not have permission to perform this action.",
    "request_id": "req_9c4a1e22"
  }
}
```

Enregistrez l’en-tête de réponse `X-Request-Id`, mais jamais la clé API. Communiquez cet identifiant lorsque vous demandez à l’assistance Chataigne d’examiner un appel.

## Étape suivante

Consultez [Trouver vos ressources](/fr/getting-started/find-your-resources) pour comprendre l’effet de chaque périmètre de clé sur la découverte des organisations et des établissements.