Clés API et permissions - Chataigne Docs

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

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.

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.

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.

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.

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 :

{
  "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 pour comprendre l’effet de chaque périmètre de clé sur la découverte des organisations et des établissements.

​Périmètre et permissions

​Clés limitées à une organisation commerciale

​Clés limitées à un établissement

​Permissions courantes

​Erreurs d’authentification

​Étape suivante

Périmètre et permissions

Clés limitées à une organisation commerciale

Clés limitées à un établissement

Permissions courantes

Erreurs d’authentification

Étape suivante