Clés d'API et webhooks

C'est la partie technique des réglages. Elle réunit 4 blocs : les clés d'API, le passeport affiché dans la page d'un partenaire, les webhooks et leur journal de livraison, puis les assistants IA connectés. Les deux premiers dépendent du droit api_access, le troisième du droit webhooks : l'un peut être ouvert quand l'autre est verrouillé. Le quatrième n'est soumis à aucun droit : une connexion accordée reste toujours visible de ceux qui peuvent y mettre fin. Une marque cliente sans le droit api_access voit quand même le deuxième bloc quand le réglage de son revendeur s'applique à elle, en version réduite.

#Ce que l'écran affiche

• Une carte par clé d'API : nom, état, début de la clé, permissions, quota quotidien, dernière utilisation et date de création. Une clé revendeur porte en plus l'étiquette « Revendeur ».
• La fenêtre de création propose 11 permissions : mint:batch, sellout:write, dispatch:write, catalog:read, catalog:write, passport:read, scans:write, nfc:verify, webhooks:read, webhooks:write, claim_codes:issue. Chacune ouvre au moins un point d'entrée de l'API. Elle arrive préremplie avec les 3 permissions de lecture (catalog:read, passport:read, webhooks:read), un quota de 1000 par jour et une validité de 365 jours. Aucune permission d'écriture n'est cochée d'avance : il faut cocher chacune soi-même.
• Cocher mint:batch affiche un avertissement : cette permission crée des produits sur la blockchain, et chaque frappe coûte du gaz (des frais de réseau) payé par la marque. Ne l'accordez qu'à un partenaire qui doit frapper.
• Cocher claim_codes:issue affiche aussi un avertissement : cette permission émet des codes d'achat, et celui qui détient un code peut devenir propriétaire de la pièce. Ne l'accordez qu'au système qui imprime les codes (émettre les codes d'achat).
• La même fenêtre propose une case « Clé revendeur », décochée par défaut. Voir Remplir le catalogue par l'API.
• Le bloc « Passeport affiché dans la page d'un partenaire » montre les adresses web du partenaire, la page du partenaire qui affiche un passeport, et une case « Envoyer les scans du QR imprimé vers la page du partenaire ». Une étiquette dit si les scans du QR vont vers la page du partenaire ou restent sur la page hébergée. Quand le réglage appliqué est celui du revendeur, une phrase le dit et nomme sa marque. Voir Afficher le passeport dans votre page.
• La fenêtre de création de webhook propose 17 types d'évènements. La liste est exactement celle que le serveur accepte, et exactement celle que nous envoyons : depuis le 12 septembre 2026, un garde-fou d'intégration continue refuse qu'elles divergent. Elle en proposait 23, dont six que rien n'envoyait.
• Le journal des livraisons : horodatage, abonnement visé, type, état, code de réponse, numéro de tentative et durée. En dépliant une ligne, vous voyez le contenu envoyé et la réponse reçue.
• La carte « Assistants IA connectés » : une ligne par assistant connecté au serveur MCP d'administration pour une de vos marques, par vous ou par un collègue. Chaque ligne donne le nom de l'application et l'adresse où elle reçoit ses réponses, ses autorisations (« Lire le catalogue », « Préparer des brouillons »), la marque, la personne qui l'a autorisée, les dates de connexion, de dernière utilisation et de fin. Voir Brancher le serveur MCP.

#Ce que vous pouvez y faire

• Créer une clé en choisissant un nom, une marque, des permissions, un quota quotidien et une durée de validité.
• Créer une clé revendeur, qui agit aussi pour les marques clientes du contrat revendeur de la marque choisie, sur tous les points d'entrée de l'API partenaire : catalogue, affichage du passeport, frappe, déclaration de vente et webhooks.
• Déclarer les adresses web d'un partenaire et la page qui affiche vos passeports, puis envoyer les scans du QR imprimé vers cette page. Un revendeur le fait une fois sur sa propre marque, pour toutes ses marques clientes.
• Supprimer le réglage propre d'une marque avec le bouton « Supprimer le réglage de cette marque », après confirmation. La marque suit alors de nouveau le réglage de son revendeur, ou la page hébergée s'il n'y en a pas.
• Pour une marque cliente dont l'offre ne comprend pas l'accès API : voir que ses scans partent vers la page de son revendeur, et les garder sur la page hébergée avec le bouton « Garder les scans du QR sur la page hébergée ». Elle ne peut pas déclarer de partenaire à elle.
• Copier le secret de la clé. Il n'est montré qu'une seule fois, à la création.
• Révoquer une clé active, après confirmation.
• Mettre fin à la connexion d'un assistant IA avec « Mettre fin à cette connexion », après confirmation. L'assistant perd son accès dès sa requête suivante.
• Créer un abonnement webhook en donnant une adresse et en cochant les évènements voulus. Le secret de signature se saisit (32 caractères au moins) ou se laisse vide : le serveur en génère alors un, que la fenêtre affiche une seule fois avec un bouton « Copier », et elle reste ouverte jusqu'à « Je l'ai enregistré ».
• Voir la liste des abonnements, chacun avec son adresse, ses évènements et un état de livraison.
• Modifier un abonnement : changer son adresse, cocher ou décocher des évènements, remplacer son secret de signature.
• Saisir l'adresse et le secret de signature d'un abonnement sans que le navigateur y propose l'identifiant ou le mot de passe enregistrés pour la console.
• Mettre un abonnement en pause, puis reprendre ses livraisons.
• Supprimer un abonnement, après avoir retapé son adresse.
• Filtrer le journal, puis relancer une livraison en échec.

#Ce qui conditionne l'accès

• Le bloc des clés d'API dépend du droit api_access, celui des webhooks du droit webhooks, qui est un droit distinct.
• À la création d'une clé, le serveur vérifie dans l'ordre que l'offre est active, que le droit api_access est présent, puis que le quota de clés n'est pas atteint.
• La base ne conserve du secret que son empreinte et un préfixe de 12 caractères. Un secret perdu ne se retrouve pas.
• Sans durée précisée, une clé expire au bout de 365 jours.
• Le bouton de création de clé reste désactivé tant que le nom, la marque ou au moins une permission manquent.
• Le bouton de création de webhook reste désactivé tant qu'une marque n'est pas choisie, que l'adresse fait moins de 10 caractères, qu'aucun évènement n'est coché, ou qu'un secret saisi fait moins de 32 caractères.
• Le bouton de révocation n'apparaît que sur les clés actives, celui de relance que sur les livraisons en échec.
• Une livraison compte comme livrée quand son code de réponse est compris entre 200 et 299.
• L'état d'un abonnement dit « Répond » ou « Ne répond plus ». Il vient des livraisons réelles, pas de l'interrupteur de pause : un abonnement en pause n'est pas un abonnement en panne, et un abonnement actif dont l'adresse ne répond plus est signalé comme tel.
• Le champ de secret d'une modification est facultatif. Laissé vide, le secret d'aujourd'hui est conservé. Rempli, il doit compter au moins 32 caractères, sinon le bouton d'enregistrement reste désactivé. Un abonnement n'est jamais sans secret : le serveur refuse d'envoyer une livraison non signée.
• Le journal va chercher les 100 dernières livraisons par abonnement, alors que le serveur en accepte 200 par appel. La liste des clés s'arrête aussi aux 100 dernières.
• Une connexion d'assistant IA ne figure pas dans la liste des clés et n'occupe aucune place du quota de clés. Elle n'apparaît que dans sa propre carte, et elle prend fin seule au bout de 90 jours au plus.

#Ce que l'écran refuse

• Sans le droit correspondant, le bloc est grisé et recouvert d'un cadenas portant « Fonctionnalité verrouillée ».
• Une adresse de webhook qui n'utilise pas HTTPS est refusée : « Webhook URL must use HTTPS ».
• Relancer une livraison réussie est refusé : « Cannot retry a successful delivery ».
• Relancer une livraison dont le contenu n'a pas été conservé est refusé : « This delivery has no stored payload and cannot be retried; trigger a fresh event instead. »
• Une adresse de partenaire qui n'est pas de la forme https://hote ou https://hote:port est refusée, comme une page de partenaire qui n'est pas sur l'une de ces adresses, et la redirection sans page de partenaire. Rien n'est enregistré, et le message du serveur nomme la valeur refusée.
• Une clé revendeur est refusée quand la marque choisie n'a pas de contrat revendeur. La fenêtre affiche le motif du refus au lieu de rester ouverte sans rien dire.
• La révocation prévient qu'elle est irréversible et que toutes les requêtes en cours avec cette clé vont échouer immédiatement.
• La suppression d'un abonnement n'est possible qu'après avoir retapé son adresse à l'identique. Elle détruit notre moitié du secret de signature : recréer l'abonnement en génère un nouveau, et le système destinataire doit être reconfiguré avant de recevoir quoi que ce soit.
• Remplacer le secret de signature a le même effet côté destinataire : tant qu'il n'a pas la nouvelle valeur, ses vérifications de signature échouent.