Clés d'API

Une clé d'API permet à un script — ou à un agent — de faire en HTTP ce qu'une personne fait dans l'interface. Vous en créez une depuis votre compte, et elle n'est affichée qu'une fois : copiez-la à ce moment-là, ou créez-en une autre.

Ce qu'une clé ouvre

Une clé appartient à une organisation, et cette organisation est tout son monde. Elle ne peut rien voir ni toucher en dehors, et aucune clé ne couvre deux organisations. Plus important encore, une clé n'est pas une seconde identité dotée de ses propres pouvoirs. Elle porte les droits du membre qui l'a créée : une clé créée par un administrateur peut écrire, une clé créée par un membre peut seulement lire. Rien n'est accessible par l'API que son créateur ne pourrait pas faire à la main.
Une clé cesse de fonctionner quand son propriétaire quitte l'organisation. Elle répond 401 à partir de ce moment, exactement comme si elle avait été révoquée — aucun accès orphelin ne survit à un départ. Révoquer la clé d'un collègue parti relève du ménage, pas d'un correctif de sécurité.

Combien de temps elle dure

Quand vous créez une clé, vous choisissez si elle a une fin : laissez N'expire jamais coché et elle reste valable jusqu'à ce que vous la révoquiez, ou décochez-le et choisissez une date — d'un jour à un an plus tard. La colonne Expire de l'écran des clés d'API vous indique laquelle est laquelle. Une fois cette date passée, la clé répond 401, exactement comme une clé révoquée.

En utiliser une

Chaque requête la transporte dans l'en-tête x-api-key :
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags"
Un seul appel indique à une clé où elle en est — quelle organisation elle ouvre, avec quel rôle, et quelles listes existent derrière. C'est tout l'amorçage : voir Découverte.

Bonnes pratiques

  • Une clé par usage. Une clé par script, par agent, par environnement. En révoquer une ne coûte alors rien aux autres.
  • Nommez-les d'après ce qu'elles font, pas d'après qui vous êtes — le nom est ce que vous lirez au moment de décider d'en révoquer une.
  • Les contacts importés enregistrent le nom de la clé qui les a créés : une clé bien nommée est donc aussi ce qui vous permet de retracer l'origine d'une audience des mois plus tard.

Ce que cela implique ailleurs

Révoquer une clé est immédiat et irréversible. Rien de ce qu'elle a créé n'est défait — les contacts, modèles et campagnes qu'elle a créés restent exactement tels qu'ils sont. La référence complète — l'enveloppe de réponse, les codes de statut, qui peut appeler quoi — se trouve dans la section API.