Clés d'API et webhooks

D’autres systèmes peuvent travailler avec votre organisation de deux façons : avec une clé d’API, ils lisent et écrivent eux-mêmes des enregistrements et lancent des automatisations ; avec un webhook, un autre service signale à kvyk.ai que quelque chose s’est passé, et une automatisation prend le relais.

Clés d’API

Une clé d’API permet à un autre système, comme votre boutique en ligne ou votre logiciel comptable, d’utiliser l’API de votre organisation dans un seul stage. Chaque clé appartient à un membre machine : un membre de votre organisation avec un nom et sans adresse e-mail, qui ne se connecte jamais et ne travaille que par ses clés. Le système lit et écrit des enregistrements en tant que ce membre, avec ses rôles de données, et lance les automatisations qu’on peut lancer depuis d’autres systèmes. Il ne peut rien faire de plus. Les enregistrements qu’il ajoute sont au membre machine, et l’historique montre le nom du membre.

Ouvrez Technique → Clés et secrets dans la barre latérale : vos clés sont sous Clés pour votre API. Seuls les Administrators voient cette liste. Elle montre chaque clé avec son Membre machine, le début de la clé, son stage, quand elle a été créée (Créée) et par qui, sa Dernière utilisation et quand elle Expire.

Créer une clé

1. Choisissez Créer une clé d’API.
2. Sous Pour, choisissez Un nouveau membre machine, ou Un membre machine existant pour donner à un membre créé avant une clé dans son autre environnement. Pour un nouveau membre, remplissez :
   • Nom : quel système l’utilise, par exemple Stock sync.
   • Rôles de données : ce qu’il peut faire. Donnez-lui-en au moins un ; tout rôle de données convient, Accès complet aussi, mais pas Non connecté.
3. Choisissez l’Environnement : Preview ou Live. Une clé n’atteint que les données de ce stage.
4. Choisissez quand elle Expire : dans 30 jours, 90 jours, 1 an ou À une date. Une clé expire toujours.
5. Choisissez Créer une clé d’API.

La clé n’est montrée qu’une fois, sous Copiez cette clé maintenant. Copiez-la et conservez-la là où le système qui l’utilise garde ses secrets : kvyk.ai ne peut pas la montrer à nouveau. Si vous la perdez, créez une nouvelle clé pour le même membre.

Le système envoie la clé avec chaque requête, sous la forme Authorization: Bearer <la clé>.

Un membre machine a une clé pour Preview et une pour Live. Une nouvelle clé pour un membre dans un environnement remplace celle qu’il y avait : l’ancienne cesse aussitôt de fonctionner. Créez un membre machine par système, pour pouvoir en arrêter un sans toucher aux autres. Une organisation peut avoir jusqu’à 50 clés.

Le membre machine

Un membre machine figure dans Personnes, marqué Membre machine. Ouvrez-le pour changer ses rôles de données ou son département, comme pour tout le monde. Il reste toujours un Member : il ne construit ni n’administre rien, et un membre machine ne coûte rien.

Pour arrêter un système pour de bon, retirez son membre machine : ses clés cessent aussitôt de fonctionner, et vous choisissez qui reprend ses enregistrements.

Quand une clé expire

Une clé qui expire dans les 14 jours est marquée Expire bientôt dans la liste, et une clé passée son jour Expirée ; la page dit combien il y en a. Chaque Administrator est prévenu sur le tableau de bord et par e-mail, dans sa langue : 14 jours avant, un jour avant et une fois qu’elle a expiré, chaque fois une seule fois. La notification ouvre les clés d’API.

Une clé expirée ne fonctionne plus : un système qui l’envoie encore est refusé, avec un message disant que la clé a expiré et à quelle date. Pour qu’un système continue de fonctionner, créez avant cette date une nouvelle clé pour son membre machine sur ce stage, et mettez la nouvelle clé dans le système. Une fois une clé révoquée ou remplacée, plus personne n’est prévenu à son sujet.

Ouvrir une application avec une clé

Un système qui ouvre l’une de vos applications dans un navigateur, comme un robot de test ou un écran au mur, peut se connecter avec sa clé. Il envoie la clé sous la forme Authorization: Bearer <la clé> en ouvrant l’adresse de l’application ; l’application s’ouvre alors en tant que membre machine et reste connectée un quart d’heure, après quoi la clé est vérifiée à nouveau. Cela ne fonctionne que si le membre machine peut ouvrir l’application : ajoutez-le, ou l’un de ses rôles de données, au public de l’application. Une clé n’ouvre que les applications de son propre stage.

Avant de renommer ou de supprimer un champ

Un système avec une clé utilise les noms de vos entités, champs et liens. En renommer ou en supprimer un sur Live casse le système jusqu’à ce qu’il soit modifié lui aussi. Quand vous publiez une telle modification alors qu’une clé pour Live fonctionne, kvyk.ai vous avertit avec les clés et la date de leur dernière utilisation, et demande encore une fois ; voir Publier et annuler des modifications. Modifiez d’abord le système, ou ajoutez le nouveau champ à côté de l’ancien et supprimez l’ancien une fois que chaque système utilise le nouveau.

Révoquer une clé

Choisissez Révoquer à côté d’une clé, puis Oui, révoquer. Les systèmes qui l’utilisent ne peuvent plus atteindre votre organisation, immédiatement. Cette action est irréversible. Le membre machine reste, et vous pouvez lui créer une nouvelle clé.

Webhooks

Un webhook permet à un autre service de lancer une automatisation en appelant une adresse web, par exemple Mollie quand un paiement arrive. La colonne Démarre sur Automatisations indique alors Depuis un autre service, et sa première case montre l’adresse sur laquelle elle écoute, par exemple /v1/hooks/mollie.

Pour que personne d’autre ne puisse la lancer, chaque webhook a son propre secret pour chaque stage. Créez le secret avec l’opération Make a new secret for a webhook automation du groupe Automations de votre Référence de l’API : un Administrator ou un Builder l’appelle pour Live ou Preview, et la réponse contient le secret et l’adresse complète pour l’autre service. Elle n’est donnée que cette fois-là. Créer un nouveau secret désactive aussitôt l’ancien.

Indiquez ensuite l’adresse à l’autre service. Le service prouve que l’appel est authentique de l’une de deux façons, comme l’indique la première case de l’automatisation :

• Par sa signature. Le service signe chaque appel avec le secret, dans l’en-tête X-Kvyk-Signature: sha256=<signature>, un HMAC-SHA256 du corps de l’appel.
• Par le secret dans l’adresse. Pour les services qui ne savent pas signer, comme Mollie, le secret fait partie de l’adresse que vous donnez au service.

Un appel mal signé est refusé. Un appel valide reçoit une réponse aussitôt, et l’automatisation s’exécute dans le stage du secret. Testez d’abord l’automatisation dans Preview avec une exécution de test, avec Un corps d’exemple, en JSON semblable à celui qu’envoie le service.