Chaque requête API doit inclure votre clé API dans l’en-tête api-key. Si la clé est absente ou n’appartient pas au programme indiqué dans l’URL, l’API répond 403.
Chaque clé appartient à un seul programme. Vous pouvez créer plusieurs clés, par exemple une par système connecté à JeriCommerce, donner à chacune uniquement l’accès dont elle a besoin et en supprimer une sans affecter les autres.
Obtenir une clé API ¶
Pour créer une clé, ouvrez Settings > Technical > API keys, puis cliquez sur Add API key. Une page s’ouvre avec ces réglages.

Nommer la clé
Saisissez un nom dans Name, par exemple le système qui l’utilisera.
Choisir quand elle expire
Dans Expiration, choisissez 15 minutes, 1 hour, 1 day, 7 days, 30 days ou Never. Les nouvelles clés démarrent sur Never. Le délai court à partir de l’enregistrement.
Choisir à quoi elle peut accéder
Restrict key est coché sur les nouvelles clés. Sous Permissions, cochez au moins une option. Le tableau plus bas indique ce que chacune permet.
Limiter les adresses IP, si vous le souhaitez
Cochez Restrict by IP pour accepter uniquement les requêtes de certaines adresses. Saisissez-en une dans IP address or CIDR range, par exemple 203.0.113.7 ou 203.0.113.0/24, puis cliquez sur Add. Vous pouvez ajouter jusqu’à 100 entrées, IPv4 ou IPv6.
Enregistrer et copier la clé
Cliquez sur Save. La fenêtre API key created affiche la clé. Copiez-la et conservez-la en lieu sûr, car vous ne pourrez plus la voir.
Si vous décochez Restrict key, la clé peut appeler toute l’API et une fuite devient bien plus risquée. Laissez cette option cochée, sauf si un système a vraiment besoin d’un accès complet.
Inclure le jeton dans les requêtes API ¶
Pour accéder aux endpoints de l’API, indiquez comme valeur de l’en-tête api-key la clé API obtenue à l’étape précédente.
Voici un exemple avec cURL qui lit un client :
curl --request GET \
--url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
--header 'api-key: {{ apiKey }}'
Gardez la clé sur votre serveur. Toute personne qui la possède peut modifier les données de vos clients : ne la placez donc jamais dans un site web, une application ou tout code exécuté sur l’appareil du client.
Les endpoints Aperçu du solde et Lister les récompenses sont publics et fonctionnent sans clé.
Ce que permet chaque autorisation ¶
Une clé restreinte ne peut faire que ce que vous cochez sous Permissions. Les webhooks Klaviyo sont aussi des appels API : leur clé a donc besoin de l’autorisation correspondant à l’action.
| Autorisation | Ce que la clé peut faire |
|---|---|
| Customers | Lire les données du client |
| Customer tokens | Obtenir un lien de téléchargement et les jetons client |
| Balance | Augmenter et réduire le solde |
| Coupons and rewards | Attribuer un coupon et échanger une récompense |
| Campaigns | Envoyer une Gift Card et attribuer des campagnes |
| Push | Envoyer une notification push |
| Earning flows | Exécuter un flux d’acquisition personnalisé |
| Subscriptions | Créer ou annuler l’abonnement du programme à JeriCommerce |
| API integration | Synchroniser les clients et les données de fidélité via la Custom API Integration |
| VTAP | Connecter un lecteur NFC VTAP |
| MCP | Utiliser cette clé avec le MCP de JeriCommerce : No access, Read ou Write. Write inclut la lecture |
Modifier une clé ¶
Dans Settings > Technical > API keys, cliquez sur les trois points d’une clé et choisissez Edit API key. Vous pouvez tout modifier, sauf la valeur de la clé.
- Expiration propose Don't change lorsque la clé a une date d’expiration, afin qu’enregistrer un autre réglage ne la déplace pas.
- Status, dans la colonne latérale, arrête une clé lorsque vous choisissez Inactive. Repassez sur Active pour la réactiver.
- Delete API key, dans le même menu, supprime la clé. Les applications qui l’utilisent cesseront de fonctionner.
La liste affiche un badge pour chaque clé : Active, Inactive ou Expired. Les clés créées avant ces réglages n’ont ni restriction ni expiration, et affichent Unrestricted jusqu’à ce que vous les restreigniez.
Erreurs de clé API ¶
Ces erreurs figurent dans le champ message de la réponse.
| Statut | message |
Signification |
|---|---|---|
401 |
API_KEY_INACTIVE |
La clé n’est pas active. Vérifiez son Status. |
401 |
API_KEY_EXPIRED |
L’Expiration de la clé est dépassée. |
403 |
API_KEY_IP_NOT_ALLOWED |
La requête provient d’une adresse hors de Restrict by IP. |
403 |
API_KEY_PERMISSION_DENIED |
La clé n’a pas l’autorisation pour cette requête. |