Clés API

Une clé API permet à un autre logiciel (un CRM, un site web, un script, un outil d'automatisation) d'appeler votre passerelle sans utiliser de compte du dashboard. Chaque clé est indépendante : elle a son propre nom, ses propres droits et ses propres plafonds, et peut être révoquée sans toucher aux autres.

Les clés se gèrent sur la page Clés API du dashboard (menu Système > Clés API, ou le bouton Gérer les clés API de la page Référence de l'API).

Qui peut faire quoi

Une clé de portée admin peut aussi gérer les clés par l'API (/api-keys). Aucune autre clé ne le peut : une clé autorisée à envoyer ne doit pas pouvoir s'accorder davantage de droits.

Créer une clé

1. Ouvrez Clés API, puis Nouvelle clé API.
2. Renseignez les options ci-dessous. Seuls le nom et la portée sont obligatoires.
3. Cliquez sur Créer la clé.
4. La clé s'affiche une seule fois, avec un bouton Copier la clé et une commande curl prête à l'emploi qui lit le dernier message (elle n'envoie rien, quelle que soit la portée). Copiez la clé dans votre application ou votre gestionnaire de secrets.
5. Cliquez sur J'ai copié la clé. La fenêtre ne se ferme pas autrement, pour que la clé ne soit pas perdue sur un clic malheureux.

Ensuite, personne ne peut plus lire la clé : ni vous, ni l'API, ni le support. La passerelle n'en garde qu'une empreinte, qui suffit à la reconnaître et ne permet pas de la reconstituer. Une clé perdue se remplace par une nouvelle.

Ce qui reste visible, c'est le préfixe : sk_ suivi des huit premiers caractères, par exemple sk_A1b2C3d. Il permet de reconnaître une clé dans la liste, ou dans la configuration de votre application, sans l'exposer.

Options

Les changements faits par Modifier valent dès l'appel suivant. La clé elle-même ne change pas : l'application continue de fonctionner avec la même valeur.

Portées

Les trois portées sont ordonnées : chacune inclut la précédente.

Certaines lectures sont réservées à Administration même si elles ne modifient rien, parce qu'elles livrent beaucoup de données d'un coup : les exports en masse, les sauvegardes (qui contiennent toute la base), la liste des comptes du dashboard (elle contient des adresses e-mail) et le journal technique. Une clé Lecture sert à consulter un message ou un appareil, pas à emporter l'installation.

Quelle que soit sa portée, une clé ne peut jamais créer, modifier ou supprimer un compte du dashboard : ces actions demandent un superadministrateur connecté au dashboard.

Un appel hors de la portée de la clé reçoit 403 FORBIDDEN_SCOPE. Un appel refusé n'entame pas votre quota.

Adresses autorisées

Laissez la liste vide et la clé fonctionne depuis n'importe où, ce qui convient à une clé utilisée depuis plusieurs endroits dont les adresses changent. Remplissez-la dès que l'application appelante a une adresse fixe : une clé copiée par erreur dans un dépôt public devient alors inutile à qui la trouve.

L'adresse contrôlée est celle de la machine qui appelle la passerelle, telle que la passerelle la voit :

• dans l'installation standard avec un domaine, le frontal HTTPS (Caddy) transmet l'adresse réelle de l'appelant, et c'est elle qui est contrôlée ;
• sur un réseau local, c'est l'adresse de la machine appelante sur ce réseau ;
• si vous placez votre propre proxy inverse devant la passerelle, déclarez-le dans GATEWAY_TRUSTED_PROXIES (voir le guide d'installation). Sinon, tous les appels semblent venir du proxy, et la liste laisse tout passer ou refuse tout. Tant qu'une liste existe, un appel dont l'adresse est illisible est refusé plutôt que laissé passer.

Plafonds

Les deux plafonds protègent contre des choses différentes :

• Appels par minute arrête une rafale : un script en boucle, une page rechargée mille fois. Il compte en mémoire et repart de zéro au redémarrage de la passerelle.
• Appels par jour plafonne le volume total d'une journée. Il est enregistré avec vos données : un redémarrage ne rend donc pas le quota. Il est compté par jour UTC, de minuit à minuit UTC, quel que soit votre fuseau horaire.

Tous les appels comptent, lectures comprises, pas seulement les envois. Un appel refusé (mauvaise portée, adresse non autorisée) n'entame pas le quota journalier ; un appel refusé pour dépassement du plafond par minute compte tout de même dans cette minute, donc réessayer plus vite n'aide pas.

Ces plafonds sont propres à chaque clé. Ils sont indépendants du quota journalier de chaque SIM réglé sur la page Appareils, qui limite les SMS réellement envoyés par chaque carte, quelle que soit leur origine. Une clé sans plafond ne peut donc pas faire dépasser son quota à une SIM.

La liste

Dernière utilisation est le moyen le plus rapide de repérer une clé que plus personne n'utilise : une clé inutilisée depuis des mois est une clé à révoquer.

Renouveler une clé

Il n'y a pas de bouton « régénérer », volontairement : remplacer une clé sur place casserait l'application qui l'utilise à l'instant même du clic. Le renouvellement se fait en trois étapes, sans interruption :

1. Créez une nouvelle clé avec la même portée et les mêmes options, nommée par exemple CRM 2026-09.
2. Placez la nouvelle clé dans l'application et vérifiez qu'elle fonctionne (sa colonne Dernière utilisation se remplit).
3. Révoquez l'ancienne clé.

Renouvelez une clé quand une personne qui la connaissait s'en va, quand elle a pu être exposée (un journal, une capture d'écran, un dépôt, un ticket de support), et sinon au rythme qui vous convient.

Révoquer ou supprimer

Les deux prennent effet immédiatement : rien n'est mis en cache, chaque appel vérifie la clé. Une clé révoquée ne peut être ni modifiée ni réactivée : créez-en une nouvelle. Une clé révoquée répond exactement comme une clé inconnue (403 INVALID_API_KEY), si bien qu'un appelant ne peut pas savoir si une valeur a existé.

La création, la révocation et la suppression des clés apparaissent dans le Journal, avec le préfixe et jamais la clé.

Bonnes pratiques

• Une clé par application. Quand un outil est retiré ou compromis, vous révoquez sa clé et rien d'autre ne s'arrête.
• La portée la plus restreinte. Envoi pour une application qui envoie, Lecture pour une qui lit. Gardez Administration pour les outils à qui vous faites autant confiance qu'à un superadministrateur.
• Des adresses autorisées dès que l'appelant a une adresse fixe.
• Un plafond journalier un peu au-dessus du volume normal : un script qui s'emballe s'arrête alors de lui-même au lieu de vider les quotas des SIM.
• La clé dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le code source, jamais dans une URL, jamais dans un e-mail. Elle voyage toujours dans l'en-tête X-API-KEY.
• En HTTPS. Sur un réseau que vous ne maîtrisez pas, n'appelez la passerelle que par son adresse https:// : en http simple, la clé traverse le réseau en clair.
• Relisez la liste de temps en temps, et révoquez les clés qui ne servent plus.

En cas de problème

Voir aussi Utiliser l'API pour le format des erreurs, et Sécurité.