Authentification
Un seul type d'identifiant, et les façons dont une requête est refusée.
L'en-tête
L'URL de base est api.openemail.uk. Chaque requête transporte la clé dans un en-tête Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Rien d'autre n'authentifie ici. Un cookie de session comme un jeton de session sont refusés avec invalid_credential_type, qui nomme l'identifiant à envoyer à la place plutôt que de vous laisser deviner devant un 401 nu.
Vérifier qu'une clé fonctionne
GET /ping est le test de fumée : il ne demande aucune portée et vous dit ce qu'est la clé.
curl "$OE/ping" -H "$AUTH"{ "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:send", "emails:read"], "roleId": null, "grantedScopes": ["emails:send", "emails:read"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}Si cet appel fonctionne et qu'un autre renvoie 401, le problème vient de la portée, pas de la clé.
scopes est la liste EFFECTIVE, et la seule qui autorise quoi que ce soit. grantedScopes est ce avec quoi la clé a été émise, et les deux ne diffèrent que lorsqu'un rôle plafonne la clé. La page Portées explique cette intersection. Un roleId à null signifie qu'il n'y a pas de plafond, soit la plus grande latitude qu'une clé puisse avoir.
Voir au nom de quelles adresses une clé peut envoyer
GET /addresses est la réponse à un 403 auquel vous ne vous attendiez pas.
curl "$OE/addresses" -H "$AUTH"{ "object": "list", "unrestricted": false, "data": [ { "object": "address", "address": "[email protected]", "enabled": true, "canSend": true }, { "object": "address", "address": "[email protected]", "enabled": true, "canSend": false } ], "domains": [ { "domain": "acme.com", "receivingVerified": true, "sendingVerified": true, "catchAll": false } ]}canSend: false a trois causes : l'adresse est désactivée, la portée d'envoi de la clé la laisse de côté (ni son domaine ni l'adresse elle-même ne figurent sur la clé), ou le domaine ne sait pas encore signer. enabled sur l'adresse et sendingVerified sur son domaine permettent de les distinguer, et c'est là l'essentiel du temps de débogage que cet endpoint fait gagner. Un domaine peut être vérifié en réception et rester incapable d'envoyer.
unrestricted: true signifie que n'importe quelle partie locale sur un domaine vérifié est acceptée, y compris celles que personne n'a encore créées.
Comment une clé est refusée
| Code | Signification |
|---|---|
| missing_api_key | Aucun en-tête Authorization. |
| invalid_credential_type | Un cookie ou un jeton de session. Envoyez une clé API. |
| invalid_api_key | Ce n'est pas une clé que nous avons émise, ou le secret ne correspond pas. |
| revoked_api_key | Émise ici, puis révoquée. Distinguée à dessein : c'est la différence entre une correction de cinq minutes et un après-midi entier. |
| expired_api_key | Émise ici, puis expirée. |
| insufficient_scope | Une vraie clé, mais sans la portée dont cet endpoint a besoin. |
La révocation prend effet au prochain appel. La ligne reste ensuite sur la page des clés, ce qui permet encore de savoir si quelque chose utilisait la clé au moment où vous l'avez tuée. L'état le plus utile de cet écran est « jamais utilisée », car c'est ainsi qu'on distingue une clé divulguée d'une dépendance bien vivante.
La rotation est l'autre façon de mettre un secret à la retraite. Elle frappe un nouveau secret pour la même clé : l'id, le nom, les portées, le rôle, la portée d'envoi ainsi que toutes les lignes de requêtes et d'activité subsistent ; seul le secret change. L'ancien cesse de fonctionner à l'instant où la rotation se termine, sans période de recouvrement, et le remplaçant n'est affiché qu'une seule fois. Depuis la console, l'action se trouve dans le même menu que Révoquer et demande d'abord une nouvelle vérification. Une clé détenant keys:write peut aussi effectuer sa propre rotation avec POST /keys/self/rotate : c'est ainsi qu'une intégration tourne ses secrets selon un calendrier sans que personne n'ouvre la console.