Aller au contenu

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.

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.

Il faut la permission « Gérer les clés API » (core:api_keys:manage).

  1. Ouvrez Paramètres > API & Webhooks (groupe Avancé), onglet Clés API.
  2. Cliquez sur Nouvelle clé API.
  3. Donnez un Nom parlant (Export comptable, Site e-commerce) : il apparaît dans le journal d’audit à chaque utilisation.
  4. Choisissez la Boutique où la clé agira. Seul un super administrateur peut choisir Toutes les boutiques.
  5. Indiquez une Expiration si l’intégration est temporaire (facultatif).
  6. Cochez seulement les permissions nécessaires. Le code technique de chaque permission (repair:tickets:read…) est affiché à droite.
  7. 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.
Fenêtre Nouvelle clé API : champs Nom, Boutique et Expiration, puis la liste des permissions à cocher avec leur code technique, et le bouton Générer la clé.
La fenêtre de création : une permission par case, avec son code technique.

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).

Onglet Clés API de Paramètres, API & Webhooks : tableau des clés avec leur nom, préfixe, boutique, nombre de permissions, dernière utilisation et statut.
Paramètres > API & Webhooks, onglet Clés API.

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.

  1. Ouvrez Mon compte (menu de votre nom, en bas de la barre latérale), onglet Mes clés API.
  2. 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.

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.

Deux en-têtes sont acceptés, au choix :

Authorization: Bearer sys_live_ab12cd34_...
X-Api-Key: sys_live_ab12cd34_...
  • 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.
Fenêtre de terminal
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).

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 :

Fenêtre de terminal
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.

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/tickets et /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.

Pour automatiser une opération réservée aux sessions, connectez un compte utilisateur dédié (rôle limité au strict nécessaire) :

Fenêtre de terminal
curl -X POST https://kiwidesk.example.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"automate@boutique.example","password":"..."}'

La 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.

  • Les routes de connexion (/api/auth/...) acceptent au plus RATE_LIMIT_AUTH_MAX requêtes (10 par défaut) par fenêtre de RATE_LIMIT_AUTH_WINDOW secondes (60), par adresse IP.
  • Les routes publiques (suivi client, signature, webhooks entrants) : RATE_LIMIT_PUBLIC_MAX (30) par RATE_LIMIT_PUBLIC_WINDOW secondes (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.

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.

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)