Authentification
Clés API, portées, erreurs 401 et 403, et les bonnes pratiques pour garder une clé secrète.
La clé API
Chaque requête porte une clé API de la boutique dans l’en-tête Authorization :
GET /v1/products HTTP/1.1
Host: api.kivoo.africa
Authorization: Bearer kv_live_EXAMPLE0000000000000000000000000000000000- Une clé appartient à une seule boutique. Elle ne donne accès qu’à ses ressources, et aucune adresse de l’API ne porte d’identifiant de boutique.
- Elle commence par
kv_live_: ce préfixe permet aux scanners de secrets (GitHub, GitGuardian…) de la reconnaître. Il n’existe pas de mode test. - Elle n’est montrée qu’une fois, à sa création. Kivoo n’en garde qu’une empreinte : une clé perdue ne se retrouve pas, on en crée une autre.
- Une boutique a au plus dix clés actives. Une clé peut expirer (30 jours, 90 jours, 1 an) ou jamais.
- Une clé révoquée l’est tout de suite et définitivement.
Les clés se gèrent dans Paramètres › Développeur › Clés API, par le propriétaire de la boutique et les membres Admin.
Les portées
Une clé porte des portées : ce qu’elle a le droit de faire, ressource par ressource. Elles sont choisies à la création et ne changent plus ; pour en changer, crée une nouvelle clé puis révoque l’ancienne.
| Ressource | Lecture | Écriture |
|---|---|---|
| Boutique | store:read | — |
| Produits | products:read | products:write |
| Commandes | orders:read | — |
| Acheteurs | customers:read | customers:write |
| Liens de paiement | payment_links:read | payment_links:write |
- L’écriture implique la lecture de la même ressource : une clé
products:writelit aussi les produits. - La boutique et les commandes ne s’écrivent pas par l’API.
- Chaque page de la référence indique la portée que l’opération demande.
- Rien de ce qu’une clé fait ne dépasse ce qu’un membre Admin de la boutique peut faire.
- Une modification faite avec une clé est inscrite au journal d’activité au nom de la clé (« Clé API « Zapier » »), pas au nom de la personne qui l’a créée.
Les erreurs d’authentification
Une requête refusée reçoit le corps d’erreur habituel (voir Conventions) avec un code stable :
| Statut | code | Ce qui se passe |
|---|---|---|
| 401 | api_key_missing | Pas d’en-tête Authorization, ou pas au format Bearer <clé>. |
| 401 | api_key_invalid | La clé n’existe pas (faute de copie, clé d’une autre plateforme). |
| 401 | api_key_revoked | La clé a été révoquée. |
| 401 | api_key_expired | La clé a dépassé sa date d’expiration. |
| 403 | insufficient_scope | La clé n’a pas la portée demandée ; details.required la nomme. |
| 403 | store_unavailable | La boutique est suspendue ou fermée : ses clés sont refusées tant qu’elle l’est. |
Les réponses 401 portent aussi l’en-tête WWW-Authenticate: Bearer realm="Kivoo API".
{
"statusCode": 403,
"code": "insufficient_scope",
"message": "This API key lacks the products:write scope",
"details": { "required": "products:write" },
"requestId": "5b0f6a2c-6a0e-4f65-9d2b-2f3d1c0b9a77",
"timestamp": "2026-09-26T10:00:00.000Z"
}Bonnes pratiques
Jamais côté client
Une clé API ne va jamais dans un navigateur, une application mobile ou un dépôt de code : quiconque la lit agit sur ta boutique. L’API refuse d’ailleurs les appels venus d’un navigateur (aucun en-tête CORS n’est renvoyé) : appelle-la depuis ton serveur.
- Range la clé dans une variable d’environnement ou un gestionnaire de secrets, jamais en dur dans le code.
- Une clé par outil : tu pourras en révoquer une sans couper les autres, et le journal d’activité dira quel outil a fait quoi.
- Donne à chaque clé les portées dont elle a besoin, pas plus.
- Pour remplacer une clé, crée la nouvelle, déploie-la, puis révoque l’ancienne.
- Au moindre doute (clé publiée par erreur, départ d’un prestataire), révoque la clé : c’est immédiat.