BreizhVoIPUn tableau de bord maison, un CRM, un script qui compte les appels du mois : ces programmes n'ont pas de doigts pour taper un mot de passe, et vous ne tenez pas à leur confier le vôtre.
Une clé API est faite pour eux. C'est un identifiant que vous créez, que vous donnez au programme, et que vous coupez le jour où il ne sert plus.
Créer la clé
Dans Paramètres, onglet Clés API.
Le nom ne sert qu'à vous : c'est ce que vous lirez dans six mois en vous demandant si cette clé sert encore. « Intégration CRM » se relit, « test2 » non.
L'expiration est facultative. Posez-en une chaque fois que l'usage a une fin connue : une reprise de données, un prestataire en mission, une maquette. Une clé qui meurt toute seule est une clé qu'on n'oublie pas de couper.
La clé complète n'apparaît qu'une seule fois, à sa création. Elle n'est pas conservée en clair : personne, pas même le support, ne peut vous la redonner.
Copiez-la immédiatement dans le coffre de votre gestionnaire de mots de passe ou dans la configuration du programme qui l'utilisera. Si vous la perdez, révoquez-la et créez-en une autre : c'est sans conséquence.
Ensuite, la liste n'en montre plus que le préfixe, les douze premiers caractères. C'est assez pour reconnaître laquelle est laquelle, et pas assez pour s'en servir.
S'en servir
Le programme envoie la clé dans un en-tête, à chaque requête :
X-API-Key: pk_live_...
C'est tout. Pas de connexion préalable, pas de jeton à rafraîchir.
L'onglet API, juste à côté, ouvre la documentation des routes filtrée selon vos droits : ce que vous y voyez est ce que votre clé pourra appeler. Vous pouvez aussi en télécharger la description pour l'importer dans votre outil de développement.
Ce qu'une clé ouvre, et ce qu'elle n'ouvre pas
C'est le point à comprendre avant de câbler quoi que ce soit : une clé n'ouvre pas tout le produit, seulement les écritures et les lectures de données courantes.
| Ouvert | Fermé |
|---|---|
| Journal des appels | Votre compte, votre mot de passe, vos sessions |
| Statistiques | La gestion des clés elle-même |
| Annuaire et groupes de contacts | Les comptes téléphoniques et leurs identifiants |
| Tout ce qui relève de l'administration de la plateforme |
Une requête hors de ce périmètre reçoit un refus explicite, qui dit que la route n'accepte pas ce mode d'authentification. Ce n'est pas une erreur de votre clé : c'est une limite voulue.
Deux règles complètent le tableau, et elles valent quel que soit votre compte.
Une clé ne porte jamais les droits d'administration de la plateforme, même si la personne qui l'a créée les possède. Elle reste dans les droits de cette personne dans cette société.
Une clé meurt avec l'accès de son propriétaire. Compte désactivé, mot de passe réinitialisé, retrait de la société, déconnexion forcée par un administrateur : les clés tombent avec le reste, et l'événement est tracé.
Couper une clé
Le bouton Révoquer la tue sur-le-champ. La requête suivante du programme est refusée.
Faites-le sans hésiter dès qu'un doute existe : un ordinateur portable perdu, un prestataire dont la mission s'achève, un dépôt de code où la clé a pu être recopiée par mégarde. Une clé révoquée reste visible dans la liste, marquée comme telle, ce qui garde la trace de ce qui a existé.
Quelques précautions qui évitent les ennuis
Une clé par usage. Deux programmes qui partagent la même clé se coupent mutuellement le jour où l'un des deux doit être révoqué.
Jamais dans le code source. Une clé recopiée dans un dépôt y reste, même après suppression du fichier : l'historique la garde. Elle vit dans la configuration du programme, à côté des autres secrets.
Créée par un compte qui dure. Une clé frappée par un stagiaire meurt avec son compte. Pour une intégration qui doit tenir, mieux vaut un compte qui restera.
Pour recevoir les évènements du standard au fil de l'eau plutôt que d'aller les chercher, ce sont les webhooks qu'il faut regarder : les deux se complètent, l'un pousse, l'autre répond.