Authentification

L’API Chariow utilise des clés API de boutique pour authentifier les requêtes. Chaque clé appartient à une boutique et porte un ensemble de scopes qui déterminent les endpoints qu’elle peut appeler.

Créer une clé API

Connexion au tableau de bord

Allez sur app.chariow.com et connectez-vous à votre compte.

Accéder aux paramètres

Cliquez sur Paramètres dans la barre latérale.

Ouvrir les clés API

Sélectionnez Clés API dans le menu des paramètres.

Créer une nouvelle clé

Cliquez sur Créer une clé API, donnez-lui un nom descriptif, choisissez ses scopes et copiez la clé générée.

Copiez votre clé API immédiatement après sa création. Pour des raisons de sécurité, la clé complète n’est affichée qu’une seule fois.

Les clés API commencent par sk_. Traitez-les comme des chaînes opaques : ne les analysez pas et ne vous fiez pas à leur longueur.

Scopes

Chaque endpoint de l’API publique exige un ou plusieurs scopes. N’accordez à chaque clé que les scopes dont son intégration a besoin : une clé qui lit seulement les produits ne peut ni lancer un paiement ni révoquer une licence, même si elle fuite.

Scopes disponibles

Scope	Libellé	Donne accès à
`store.read`	Lire la boutique	Nom, devise, réglages et informations publiques de la boutique.
`products.read`	Lire les produits	Produits, prix et informations publiées.
`sales.read`	Lire les ventes	Ventes, statuts et montants.
`customers.read`	Lire les clients	Liste des clients et historique d’achat.
`customers.pii.read`	Lire les coordonnées des clients	Adresses e-mail et numéros de téléphone des clients. Inclut `customers.read`.
`discounts.read`	Lire les réductions	Codes de réduction et leurs conditions.
`licenses.read`	Lire les licences	Clés de licence et leurs activations.
`licenses.write`	Gérer les licences	Activer et révoquer des clés de licence. Inclut `licenses.read`.
`affiliates.read`	Lire les affiliés	Profils et codes des affiliés.
`affiliates.write`	Inviter des affiliés	Envoyer des invitations d’affiliation. Inclut `affiliates.read`.
`webhooks.read`	Lire les webhooks	Webhooks Pulse configurés sur la boutique.
`webhooks.write`	Gérer les webhooks	Créer et supprimer les connexions Make, Zapier et n8n. Inclut `webhooks.read`.
`checkout.write`	Créer des paiements	Lancer un paiement pour un produit au nom d’un client.

Un scope d’écriture inclut toujours son scope de lecture : accorder licenses.write accorde aussi licenses.read.

Scopes requis par endpoint

Endpoint	Scopes requis
`GET /v1/store`	`store.read`
`GET /v1/products`, `GET /v1/products/{productId}`	`products.read`
`POST /v1/checkout`	`checkout.write`
`GET /v1/sales`, `GET /v1/sales/{saleId}`	`sales.read`
`GET /v1/customers`, `GET /v1/customers/{customerId}`	`customers.read` et `customers.pii.read`
`GET /v1/licenses`, `GET /v1/licenses/{licenseKey}`, `GET /v1/licenses/{licenseKey}/activations`	`licenses.read`
`POST /v1/licenses/{licenseKey}/activate`, `POST /v1/licenses/{licenseKey}/revoke`	`licenses.write`
`GET /v1/discounts`, `GET /v1/discounts/{discountId}`	`discounts.read`
`GET /v1/pulses`, `GET /v1/pulses/{pulseId}`	`webhooks.read`
`GET /v1/affiliates/{affiliateCode}`	`affiliates.read`
`POST /v1/affiliates/invitations`	`affiliates.write`

Les endpoints clients renvoient des coordonnées, ils exigent donc les deux scopes clients. Accorder customers.pii.read suffit, car il inclut customers.read.

Attribution des scopes

Choix des scopes : choisissez les scopes lors de la création de la clé. Si vous n’en choisissez aucun, la clé reçoit tous les scopes que votre rôle d’équipe autorise.
Modification des scopes : vous pouvez modifier les scopes d’une clé existante depuis Paramètres → Clés API sans la régénérer. Les intégrations qui l’utilisent continuent de fonctionner avec les nouvelles permissions.
Rôles d’équipe : une clé ne peut jamais dépasser le rôle du membre de l’équipe qui la crée. Par exemple, un membre ayant le rôle Support ne peut pas accorder licenses.write, checkout.write, affiliates.write ni webhooks.write.
Changement de rôle : si le rôle du créateur est rétrogradé, ses clés perdent les scopes que le nouveau rôle n’autorise plus. Une promotion du créateur n’ajoute aucun scope aux clés existantes.
Membres désactivés : lorsqu’un membre de l’équipe perd l’accès à la boutique, les clés API et connexions MCP qu’il a créées sont supprimées et cessent immédiatement de fonctionner. Réactiver le membre ne les restaure pas.
Clés existantes : les clés créées avant l’introduction des scopes ont reçu tous les scopes que le rôle de leur créateur autorisait à ce moment-là.
Nouveaux scopes : les scopes ajoutés plus tard au catalogue ne sont jamais accordés automatiquement aux clés existantes. Ajoutez-les vous-même à une clé lorsqu’une intégration en a besoin.

Effectuer des requêtes authentifiées

Incluez votre clé API dans l’en-tête Authorization de chaque requête :

Authorization: Bearer VOTRE_CLE_API

Exemple de requête

curl -X GET "https://api.chariow.com/v1/store" \
  -H "Authorization: Bearer VOTRE_CLE_API"

const response = await fetch('https://api.chariow.com/v1/store', {
  headers: {
    'Authorization': 'Bearer VOTRE_CLE_API'
  }
});

import requests

headers = {
    'Authorization': 'Bearer VOTRE_CLE_API'
}

response = requests.get('https://api.chariow.com/v1/store', headers=headers)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.chariow.com/v1/store');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer VOTRE_CLE_API'
]);

Bonnes pratiques de sécurité

Accorder le moins de scopes possible

N’accordez à chaque clé que les scopes dont son intégration a besoin. Un script de reporting a besoin de sales.read, pas de licenses.write.

Utiliser des variables d'environnement

Stockez les clés API dans des variables d’environnement, pas dans votre code :

# Fichier .env
CHARIOW_API_KEY=votre_cle_api

# Accès dans votre code
process.env.CHARIOW_API_KEY

Utiliser des clés différentes par environnement

Créez des clés API distinctes pour le développement, le staging et la production. Cela limite l’impact en cas de compromission d’une clé.

Renouveler les clés régulièrement

Créez périodiquement de nouvelles clés et supprimez les anciennes. Cela réduit la fenêtre d’opportunité pour les clés compromises.

Surveiller l'utilisation des clés

Vérifiez régulièrement l’utilisation de vos clés API dans le tableau de bord. Recherchez les schémas inhabituels qui pourraient indiquer un accès non autorisé.

Restreindre au côté serveur

N’exposez jamais votre clé API dans le code côté client (JavaScript s’exécutant dans les navigateurs). Tous les appels API doivent être effectués depuis votre serveur.

Erreurs d’authentification

Si la clé est absente ou invalide, vous recevrez une réponse 401 Non autorisé. Ces messages sont toujours renvoyés en anglais :

{
  "message": "API key is missing. Please provide a valid API key. Help: https://docs.chariow.com",
  "errors": []
}

Message	Cause	Solution
`API key is missing. Please provide a valid API key. Help: https://docs.chariow.com`	Pas d’en-tête `Authorization: Bearer`	Ajoutez l’en-tête à votre requête
`Invalid API key. Please check again. Help: https://docs.chariow.com`	La clé est mal formée, a été supprimée, ou son créateur n’est plus un membre actif de l’équipe	Vérifiez la clé ou créez-en une nouvelle dans votre tableau de bord

Erreurs de scope

Si la clé est valide mais ne possède pas un scope exigé par l’endpoint, vous recevrez une réponse 403 Forbidden qui liste les scopes manquants :

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="checkout.write"

{
  "message": "Il manque à cet identifiant le scope requis : checkout.write. Modifiez ses permissions depuis votre tableau de bord.",
  "data": [],
  "errors": {
    "scopes": ["checkout.write"]
  }
}

errors.scopes liste chaque scope manquant. Utilisez ce champ plutôt que message dans votre code : le message est traduit dans la langue de la requête (ici en français).
L’en-tête WWW-Authenticate porte les mêmes scopes, séparés par des espaces.
Pour corriger l’erreur, ajoutez les scopes manquants à la clé dans Paramètres → Clés API, ou demandez-le à un membre de l’équipe dont le rôle les autorise.

Limitation de débit

Les clés API sont soumises à une limitation de débit pour garantir une utilisation équitable :

100 requêtes par minute par clé API pour tous les endpoints sauf le paiement
100 requêtes par minute par clé API pour POST /v1/checkout, comptées séparément

En cas de dépassement, vous recevrez une réponse 429 Too Many Requests. Consultez Limites de débit pour plus de détails.

Besoin de limites plus élevées ? Contactez notre équipe support à support@chariow.com.

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Créer une clé API

Scopes

Scopes disponibles

Scopes requis par endpoint

Attribution des scopes

Effectuer des requêtes authentifiées

Exemple de requête

Bonnes pratiques de sécurité

Erreurs d’authentification

Erreurs de scope

Limitation de débit

Prochaines étapes

Référence API

Limites de débit

​Créer une clé API

​Scopes

​Scopes disponibles

​Scopes requis par endpoint

​Attribution des scopes

​Effectuer des requêtes authentifiées

​Exemple de requête

​Bonnes pratiques de sécurité

​Erreurs d’authentification

​Erreurs de scope

​Limitation de débit

​Prochaines étapes

Référence API

Limites de débit

Créer une clé API

Scopes

Scopes disponibles

Scopes requis par endpoint

Attribution des scopes

Effectuer des requêtes authentifiées

Exemple de requête

Bonnes pratiques de sécurité

Erreurs d’authentification

Erreurs de scope

Limitation de débit

Prochaines étapes