Générer et gérer vos clés d’API

Une clé d’API ne s’envoie pas sur les appels de l’API publique : vous l’échangez une seule fois contre un jeton, et c’est ce jeton qui authentifie ensuite vos requêtes. Cet article décrit où générer une clé, ce que l’écran ne permet pas de faire, et comment remplacer ou faire supprimer une clé existante. Les appels que la clé ouvre sont décrits dans la référence OpenAPI, sur doc.developers.beedeez.com .

⚠️ Prérequis : l’option d’API publique doit être ouverte sur votre compte. Aucun écran du back-office ne l’active, c’est votre interlocuteur Beedeez qui l’ouvre. Sans elle, l’entrée Developers API n’apparaît pas.

⚠️ Droits nécessaires : le droit Modifier la personnalisation, celui qui donne accès au menu Configuration. Il n’existe pas de droit dédié aux clés d’API.

L’entrée Developers API n’est pas proposée lorsque vous configurez un département : elle n’existe qu’au niveau du compte.

Générer une clé

Ouvrez Configuration > Intégration > Developers API, puis suivez ces étapes dans l’ordre :

1. Basculez le sélecteur de Désactivé à Activé.
2. Cliquez sur Tout sauvegarder, en bas de la colonne de gauche. Tant que l’activation n’est pas enregistrée, le bouton de génération n’apparaît pas.
3. Cliquez sur Générer la clé. La valeur s’affiche dans le champ situé à droite du bouton : 64 caractères hexadécimaux. Avant la génération, ce champ contient une suite de tildes, qui n’est pas une clé.
4. Cliquez sur Copier la clé, puis collez la valeur dans votre coffre à secrets.

La clé se présente ensuite dans le champ appSecret de l’appel POST /v1/token : S’authentifier sur l’API.

La clé ne s’affiche qu’une seule fois

⚠️ « La clé ne peut être consultée qu’une seule fois. Veuillez la copier et la conserver. » C’est l’avertissement affiché au-dessus du bouton, et il décrit exactement le comportement. Copier la clé place la valeur dans le presse-papiers et vide le champ dans le même geste ; un rechargement de la page la perd également. Ensuite, aucun écran du back-office ni aucun appel de l’API publique ne la réaffiche : si vous ne l’avez pas mise à l’abri, considérez-la comme perdue et générez-en une autre.

Collez la clé dans votre coffre à secrets avant de quitter la page. Ne la transmettez ni par email, ni dans un ticket, ni dans un canal de discussion. Une clé se traite comme un mot de passe : elle donne à elle seule accès aux données du compte.

Ce que l’écran ne permet pas

• Nommer une clé. Il n’y a aucun champ à renseigner, donc rien ne distingue deux clés. Tenez vous-même la liste : date de génération et destination.
• Consulter les clés existantes. L’écran n’affiche ni la liste des clés, ni leur nombre, ni leur dernière utilisation.
• Limiter la portée d’une clé. L’écran ne propose ni sélecteur de périmètre, ni mode lecture seule, ni restriction à un groupe ou à un département. La portée est définie au niveau du compte et toutes les clés du compte reçoivent la même.
• Révoquer une clé. Aucun bouton de suppression n’est proposé.

Une clé n’expire pas : elle reste valable tant qu’elle n’est pas supprimée. Elle appartient au compte et non à la personne qui l’a générée, donc la désactivation ultérieure de cet administrateur ne l’interrompt pas.

Les effets à connaître avant d’ajouter une clé

⚠️ Remettre le sélecteur sur « Désactivé » ne révoque rien. Cela empêche seulement de générer de nouvelles clés. Les clés déjà émises continuent de fonctionner et l’API répond toujours.

⚠️ Générer une clé ne remplace pas la précédente. Chaque génération ajoute une clé. Toutes restent valables en parallèle, y compris celles dont vous avez oublié l’existence.

⚠️ Deux intégrations ne peuvent pas fonctionner en même temps sur le même compte, même avec deux clés différentes. Le jeton de rafraîchissement est unique par compte : dès qu’une intégration échange sa clé contre un jeton, celui que détenait l’autre cesse de fonctionner. La seconde doit rééchanger sa clé, ce qui coupe la première à son tour. Prévoyez une seule intégration active par compte.

Faire supprimer une clé

La suppression ne se fait pas depuis le back-office. Demandez-la à votre interlocuteur Beedeez en indiquant le compte et la clé concernée.

La suppression empêche l’émission de nouveaux jetons dès qu’elle est effectuée, mais un jeton d’accès déjà émis n’est pas annulé : il reste valable jusqu’à 6 heures après sa création. Comptez ce délai avant de considérer l’accès comme fermé. Si une clé a fuité, signalez-le comme un incident de sécurité plutôt que d’attendre cette expiration.

Remplacer une clé

La rotation sans interruption de service n’est pas possible. Deux clés peuvent exister en même temps, mais elles ne peuvent pas servir en même temps, pour la raison décrite plus haut. Le remplacement demande donc une fenêtre d’interruption :

1. Générez la nouvelle clé et mettez-la à l’abri.
2. Arrêtez l’intégration qui utilise l’ancienne clé.
3. Déployez la nouvelle clé, puis redémarrez l’intégration.
4. Vérifiez que les appels aboutissent, puis demandez la suppression de l’ancienne clé.

Ne demandez la suppression qu’à la fin. Dans l’ordre inverse, il ne vous reste aucun repli si la nouvelle clé ne fonctionne pas.

Pour aller plus loin

• S’authentifier sur l’API : ce que vous faites de la clé une fois obtenue, et les erreurs d’intégration les plus fréquentes.
• Les ressources disponibles : ce que l’API expose réellement, à lire avant de dimensionner un développement.
• API publique, webhooks, callbacks : que choisir : vérifier qu’un connecteur existant ne couvre pas déjà le besoin.
• Attribuer les droits : donner Modifier la personnalisation à la bonne personne.