Clés API

GET /keys liste chaque clé que l'appelant peut voir, les plus récentes d'abord et une page à la fois, avec son statut, ses portées, son rôle, sa portée d'envoi, sa dernière utilisation et qui l'a créée et modifiée en dernier. GET /keys/{id} en lit une. Aucune lecture ne renvoie jamais de secret : maskedKey suffit pour distinguer deux clés. Les deux demandent keys:read.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys crée une clé et renvoie son secret dans token, une seule fois. Par défaut, la portée est emails:send, et le rôle, la portée d'envoi et l'expiration sont ceux de l'appelant.
• —PATCH /keys/{id} renomme une clé, remplace ses portées ou sa portée d'envoi, et la désactive puis la réactive avec enabled. Désactiver est le choix réversible : la clé garde tout et est refusée avec inactive_api_key jusqu'à sa réactivation.
• —POST /keys/{id}/rotate donne un nouveau secret à une clé et le renvoie une fois. L'ancien secret cesse de fonctionner à l'instant où l'appel revient.
• —POST /keys/{id}/revoke retire une clé définitivement, avec un reason facultatif. DELETE /keys/{id} la retire ensuite de la liste et garde son historique.
• —Tous demandent keys:manage. Renouveler la clé qui appelle fonctionne aussi avec keys:write, exactement comme POST /keys/self/rotate.

Chaque modification est vérifiée par rapport à la clé qui la fait. Une clé qui sortirait de l'appelant sur un axe quelconque est refusée avec 403 beyond_caller_authority, et param nomme l'axe :

• —Portées : seulement celles que détient l'appelant une fois restreintes par son propre rôle.
• —Rôle : un appelant plafonné par un rôle ne peut créer et gérer que des clés plafonnées par le même rôle.
• —Expiration : un appelant qui expire ne peut créer et gérer que des clés qui n'expirent pas plus tard.
• —Mode : une clé de test n'atteint que des clés de test.
• —Portée d'envoi : seulement des domaines et des adresses à l'intérieur de celle de l'appelant, et détenir une adresse ne couvre jamais tout son domaine.

La console vous demande de vous vérifier à nouveau avant de créer ou de renouveler une clé. Un appel fait avec une clé ne peut pas le demander, donc keys:manage est un identifiant qui fabrique des identifiants : une clé divulguée qui la détient peut créer ses propres clés, jusqu'à sa propre portée, qui continuent de fonctionner après sa révocation.

• —Ne donnez keys:manage qu'à une automatisation dont le travail est d'émettre des clés, jamais à une clé qui envoie du courrier.
• —Restreignez cette clé : un rôle, une portée d'envoi et une expiration. Tout ce qu'elle crée hérite des trois et ne peut jamais les dépasser.
• —Surveillez GET /keys/activity. Chaque clé qu'elle crée, modifie ou révoque lui est attribuée par son nom, donc une fuite apparaît sous forme de clés inattendues.
• —keys:read expose le journal des requêtes, adresses IP et agents utilisateurs compris. Traitez-la comme un accès d'audit.

GET /keys/requests et GET /keys/{id}/requests lisent chaque appel authentifié fait par une clé, le plus récent d'abord : méthode, chemin, statut, code d'erreur, durée, IP et agent utilisateur, jamais un corps ni une chaîne de requête. keyIds, failedOnly, since et until sont les filtres de la console. GET /keys/activity et GET /keys/{id}/activity lisent ce qui est arrivé aux clés, actor indiquant qui l'a fait, en @username ou API key <name>. Rien n'est purgé, et une clé supprimée garde son historique.