Authentification et clés API
Un programme s’identifie auprès de KiwiDesk avec une clé API. Une clé n’agit que dans une boutique (ou dans toutes, si un super administrateur l’a voulu) et avec les permissions cochées à sa création, jamais plus que celles de la personne qui l’a créée.
Les sortes de clés
Section intitulée « Les sortes de clés »| Préfixe | Sorte | Créée dans | Agit… |
|---|---|---|---|
sys_live_ |
Clé de boutique | Paramètres > API & Webhooks, onglet Clés API | pour une intégration (ERP, site web, outil comptable), sans personne derrière |
usr_live_ |
Clé personnelle | Mon compte, onglet Mes clés API | au nom de la personne qui l’a créée, dans sa boutique active |
plg_live_ |
Jeton de plugin | Donné à l’installation d’un plugin avec serveur | pour le serveur du plugin, avec les droits accordés au plugin |
Les clés créées avant l’arrivée des clés personnelles commencent par kd_live_ : ce sont des clés
de boutique, elles fonctionnent toujours.
Une clé a la forme sys_live_ab12cd34_ suivie de 43 caractères. Les 8 caractères après le préfixe
(le préfixe affiché dans les listes, ici ab12cd34) ne sont pas secrets : ils servent à
reconnaître la clé. Le reste est le secret. KiwiDesk n’en garde qu’une empreinte : la clé
complète n’est affichée qu’une seule fois, à sa création.
Créer une clé de boutique
Section intitulée « Créer une clé de boutique »Il faut la permission « Gérer les clés API » (core:api_keys:manage).
- Ouvrez Paramètres > API & Webhooks (groupe Avancé), onglet Clés API.
- Cliquez sur Nouvelle clé API.
- Donnez un Nom parlant (
Export comptable,Site e-commerce) : il apparaît dans le journal d’audit à chaque utilisation. - Choisissez la Boutique où la clé agira. Seul un super administrateur peut choisir Toutes les boutiques.
- Indiquez une Expiration si l’intégration est temporaire (facultatif).
- Cochez seulement les permissions nécessaires. Le code technique de chaque permission
(
repair:tickets:read…) est affiché à droite. - Cliquez sur Générer la clé, puis copiez-la aussitôt dans le gestionnaire de secrets de votre intégration : le message Copiez cette valeur maintenant : elle ne sera plus jamais affichée le rappelle.

La liste des clés montre pour chacune son préfixe, sa boutique, son nombre de permissions, sa Dernière utilisation (date et adresse IP) et son statut (Active, Expirée, Révoquée).

Créer une clé personnelle
Section intitulée « Créer une clé personnelle »Une clé personnelle sert à vos propres scripts. Elle agit en votre nom, dans votre boutique active au moment de la création, avec une partie de vos permissions.
- Ouvrez Mon compte (menu de votre nom, en bas de la barre latérale), onglet Mes clés API.
- Cliquez sur Nouvelle clé personnelle, nommez-la, cochez les permissions, puis générez-la et copiez-la.
Il faut la permission core:api_keys:personal. Vous pouvez toujours révoquer vos propres clés,
même si vous perdez cette permission.
Ce que la clé peut faire, à chaque requête
Section intitulée « Ce que la clé peut faire, à chaque requête »KiwiDesk recalcule les droits d’une clé à chaque requête :
- clé de boutique : les permissions cochées, réduites à celles que son créateur détient encore dans cette boutique. Si le créateur perd un droit, la clé le perd aussi ; si son compte est désactivé, la clé est refusée ;
- clé personnelle : les permissions cochées que la personne détient encore dans la boutique de la clé ;
- jeton de plugin : les permissions et les boutiques accordées au plugin ; plugin désactivé, jeton refusé.
Une clé n’est jamais super administrateur : elle ne voit que ce que ses permissions ouvrent. Par
exemple, sans repair:pricing:view_cost, les tickets renvoyés ont marginCents: null.
Envoyer la clé
Section intitulée « Envoyer la clé »Deux en-têtes sont acceptés, au choix :
Authorization: Bearer sys_live_ab12cd34_...X-Api-Key: sys_live_ab12cd34_...Choisir la boutique
Section intitulée « Choisir la boutique »- Clé liée à une boutique (cas normal) : elle agit toujours dans sa boutique, rien à préciser.
- Clé valable pour toutes les boutiques, ou jeton d’un plugin autorisé dans plusieurs
boutiques : envoyez l’identifiant de la boutique visée dans l’en-tête
X-Store-Id.
curl https://kiwidesk.example.com/api/repair/tickets \ -H "Authorization: Bearer sys_live_ab12cd34_..." \ -H "X-Store-Id: 01a1bafb-6510-738f-98da-85c97912cce8"Sans cet en-tête, une route qui travaille dans une boutique répond 400 BAD_REQUEST
(« Sélectionnez une boutique (en-tête X-Store-Id pour les clés API non liées à une boutique) »).
L’identifiant d’une boutique se lit avec GET /api/stores (permission core:stores:read).
Révoquer une clé
Section intitulée « Révoquer une clé »Dans la liste des clés, cliquez sur l’icône Révoquer de la ligne, puis confirmez. La clé est
refusée immédiatement (401 INVALID_API_KEY). Par l’API :
curl -X POST https://kiwidesk.example.com/api/api-keys/<id>/revoke \ -H "Authorization: Bearer <jeton de session d'un administrateur>"Révoquez une clé dès qu’elle a pu fuiter (commit dans un dépôt, capture d’écran, ancien prestataire) : créez-en une nouvelle, mettez à jour l’intégration, puis révoquez l’ancienne.
Ce qu’une clé ne peut pas faire
Section intitulée « Ce qu’une clé ne peut pas faire »Certaines routes exigent une personne connectée et répondent à une clé :
{ "statusCode": 403, "code": "PERMISSION_DENIED", "message": "Cette opération nécessite une session utilisateur (indisponible avec une clé API)"}C’est le cas notamment de :
- la prise en charge d’un appareil (
POST /api/repair/ticketset/api/repair/tickets/batch) : le ticket a un auteur, une personne qui a vu l’appareil ; - la caisse et les encaissements au comptoir ;
- la gestion des clés API, des webhooks, des plugins, des rôles et des utilisateurs, les réglages de sécurité et la double authentification.
Une clé peut en revanche lire et modifier les tickets existants (changement de statut, notes…), les clients, les appareils, le stock, et lire factures et exports, selon ses permissions.
Utiliser une session pour ces opérations
Section intitulée « Utiliser une session pour ces opérations »Pour automatiser une opération réservée aux sessions, connectez un compte utilisateur dédié (rôle limité au strict nécessaire) :
curl -X POST https://kiwidesk.example.com/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"automate@boutique.example","password":"..."}'const response = await fetch("https://kiwidesk.example.com/api/auth/login", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ email: process.env.KIWIDESK_EMAIL, password: process.env.KIWIDESK_PASSWORD }),});const { accessToken, expiresIn } = await response.json(); // expiresIn: 900 secondesLa réponse contient accessToken (jeton JWT valable 15 minutes, expiresIn: 900), envoyé
ensuite dans Authorization: Bearer <accessToken>, et pose un cookie kd_refresh (HttpOnly) qui
permet d’obtenir un nouveau jeton avec POST /api/auth/refresh. Un compte avec double
authentification reçoit d’abord une demande de code : un automate ne peut pas y répondre. Le
jeton agit dans la boutique active du compte ; la prise en charge accepte aussi storeId dans le
corps de la requête. Une session verrouillée par inactivité répond 423 SESSION_LOCKED.
Limites de débit
Section intitulée « Limites de débit »- Les routes de connexion (
/api/auth/...) acceptent au plusRATE_LIMIT_AUTH_MAXrequêtes (10 par défaut) par fenêtre deRATE_LIMIT_AUTH_WINDOWsecondes (60), par adresse IP. - Les routes publiques (suivi client, signature, webhooks entrants) :
RATE_LIMIT_PUBLIC_MAX(30) parRATE_LIMIT_PUBLIC_WINDOWsecondes (60). - Les autres routes, appelées avec une clé, n’ont pas de quota par clé. Restez raisonnable : préférez les webhooks à une interrogation toutes les secondes, et demandez des pages de 100 à 200 éléments plutôt que mille requêtes.
Au-delà d’une limite, l’API répond 429 RATE_LIMITED (« Trop de requêtes, réessayez plus tard ») :
attendez puis réessayez.
Traçabilité
Section intitulée « Traçabilité »Chaque création et révocation de clé est inscrite au journal d’audit. Chaque écriture faite avec une clé est tracée ; les lectures le sont une fois par minute, par clé et par adresse (une intégration qui interroge souvent ne noie pas le journal). La date et l’adresse IP de la dernière utilisation sont affichées dans la liste des clés.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »| Réponse | Cause probable |
|---|---|
401 INVALID_API_KEY |
Clé mal copiée (espace, retour à la ligne), révoquée, expirée, ou créateur désactivé |
403 PERMISSION_DENIED |
Permission non cochée, ou perdue par le créateur ; details.required liste celles attendues |
403 PERMISSION_DENIED « session utilisateur » |
Route réservée aux sessions : voir ci-dessus |
403 STORE_ACCESS_DENIED |
X-Store-Id désigne une boutique inconnue, fermée ou hors de portée de la clé |
400 « Sélectionnez une boutique » |
Clé valable pour toutes les boutiques sans en-tête X-Store-Id |
400 « En-tête X-Store-Id invalide » |
La valeur n’est pas un identifiant de boutique (UUID) |