Base de connaissances

Clés API

Une clé par tâche, limitée aux droits et aux expéditeurs dont elle a besoin, avec chaque appel journalisé.

Détails

Créées dans Paramètres → Clés API, sur un espace de travail qui vous appartient. Le secret n’est affiché qu’une fois, et chaque clé est une clé oe_live_.
Une clé ne détient que les droits choisis, et une nouvelle commence par emails:send. Elle peut aussi porter un rôle, qui est un plafond et non une seconde autorisation : GET /ping renvoie les droits que la clé nomme et ceux que le rôle lui laisse, si bien qu’un 403 sur un droit que la clé détient visiblement a une cause lisible.
Le périmètre d’envoi compte jusqu’à 25 domaines entiers et 50 adresses isolées. Un domaine entier couvre aussi les adresses qui y sont ajoutées ensuite, et un expéditeur hors de la liste est refusé avec un 403.
Une expiration facultative fait tomber une clé d’elle-même, jusqu’à dix ans à l’avance.
Le renouvellement ne change que le secret : l’identifiant, les droits, le périmètre d’envoi et l’historique des requêtes se poursuivent, et l’ancien secret cesse de fonctionner dès que le nouveau est créé. Une clé disposant de keys:write peut se renouveler elle-même via l’API. La révocation est une mise à jour et non une suppression, donc un appel ultérieur reçoit revoked_api_key.
Chaque appel authentifié est journalisé avec sa méthode, son chemin, son statut, son code d’erreur, sa durée, son IP et son agent utilisateur, jamais avec un corps ou des paramètres de requête. La page de la clé le présente en Analyses, Activité et Requêtes, avec les routes les plus sollicitées, leur taux d’échec et leur latence médiane, et les mêmes vues couvrent plusieurs clés à la fois. Le journal est conservé, pas élagué.
Tout ce que fait la page est aussi dans l'API et le SDK : GET /keys et GET /keys/{id} lisent les clés sans leurs secrets, POST /keys en crée une, PATCH /keys/{id} la renomme, change ses portées ou sa portée d'envoi et la désactive puis la réactive, et rotate, revoke et delete font ce qu'ils disent. Le journal des requêtes et l'activité se lisent de la même façon, pour une clé ou pour toutes, avec les filtres de la page. Lire demande keys:read et chaque modification keys:manage, deux portées qu'aucune clé ne détient tant que personne ne les lui a données. Le serveur MCP lit aussi le journal et l'activité, sous les noms listApiKeyRequests et listApiKeyActivity.
Une clé ne crée ni n'atteint jamais une clé plus large qu'elle-même : ses portées, son rôle, son expiration, son mode et sa portée d'envoi doivent tous rester à l'intérieur de la clé qui appelle. La vérification renforcée ne peut pas s'appliquer à un appel fait avec une clé, donc keys:manage est un identifiant qui fabrique des identifiants. Ne la donnez qu'à une automatisation qui émet des clés, avec son propre rôle, sa propre portée d'envoi et sa propre expiration, et surveillez l'onglet Activité, où tout ce qu'elle fait lui est attribué.
Ce qui manque : une clé ne peut pas être liée à des adresses IP, et aucune clé en mode test ne peut être créée.