Authentifizierung
Ein einziger Credential-Typ und die Arten, auf die eine Anfrage abgelehnt wird.
Der Header
Die Basis-URL lautet api.openemail.uk. Jede Anfrage übergibt den Schlüssel in einem Authorization-Header.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Nichts anderes authentifiziert hier. Ein Session-Cookie und ein Session-Token werden beide mit invalid_credential_type abgelehnt, das benennt, welches Credential stattdessen zu senden ist, statt Sie vor einem nackten 401 raten zu lassen.
Prüfen, ob ein Schlüssel funktioniert
GET /ping ist der Smoke-Test: Er benötigt keinen Scope und sagt Ihnen, was der Schlüssel ist.
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"}Wenn das funktioniert und etwas anderes mit 401 antwortet, liegt das Problem am Scope, nicht am Schlüssel.
scopes ist die EFFEKTIVE Liste und die einzige, die überhaupt etwas autorisiert. grantedScopes ist das, womit der Schlüssel ausgestellt wurde; beide unterscheiden sich nur dann, wenn eine Rolle den Schlüssel begrenzt. Die Seite Scopes erklärt diese Schnittmenge. Ein roleId von null bedeutet keine Obergrenze, und weiter reicht ein Schlüssel nicht.
Ansehen, als wer ein Schlüssel senden darf
GET /addresses ist die Antwort auf ein 403, mit dem Sie nicht gerechnet haben.
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 hat drei Ursachen: Die Adresse ist abgeschaltet, der Sende-Scope des Schlüssels lässt sie aus (weder ihre Domain noch die Adresse selbst steht auf dem Schlüssel), oder die Domain kann noch nicht signieren. enabled an der Adresse und sendingVerified an ihrer Domain unterscheiden diese Fälle, und darin liegt der größte Teil der Debugging-Zeit, die dieser Endpunkt spart. Eine Domain kann für den Empfang verifiziert sein und trotzdem nicht senden können.
unrestricted: true bedeutet, dass jeder local-part auf einer verifizierten Domain akzeptiert wird, auch solche, die noch niemand angelegt hat.
Wie ein Schlüssel abgelehnt wird
| Code | Bedeutet |
|---|---|
| missing_api_key | Überhaupt kein Authorization-Header. |
| invalid_credential_type | Ein Cookie oder ein Session-Token. Senden Sie einen API-Schlüssel. |
| invalid_api_key | Kein von uns ausgestellter Schlüssel, oder das Secret stimmt nicht. |
| revoked_api_key | Hier ausgestellt, dann widerrufen. Bewusst als eigener Fall geführt. Es ist der Unterschied zwischen fünf Minuten und einem ganzen Nachmittag. |
| expired_api_key | Hier ausgestellt, dann abgelaufen. |
| insufficient_scope | Ein echter Schlüssel, aber ohne den Scope, den dieser Endpunkt benötigt. |
Ein Widerruf greift ab dem nächsten Aufruf. Die Zeile bleibt danach auf der Schlüsselseite stehen, sodass Sie weiterhin erkennen, ob etwas den Schlüssel genutzt hat, als Sie ihn stillgelegt haben. Der nützlichste Zustand auf diesem Bildschirm ist „nie verwendet“, denn daran unterscheidet man einen geleakten Schlüssel von einer aktiven Abhängigkeit.
Rotieren ist der andere Weg, ein Secret außer Dienst zu stellen. Dabei wird ein neues Secret für denselben Schlüssel erzeugt, sodass id, Name, Scopes, Rolle, Sende-Scope sowie sämtliche Request- und Aktivitätszeilen bestehen bleiben; nur das Secret ändert sich. Das alte funktioniert in dem Moment nicht mehr, in dem die Rotation abgeschlossen ist, ohne Überlappungsfenster, und der Ersatz wird genau einmal angezeigt. In der Konsole steht die Funktion im selben Menü wie Revoke und verlangt zuvor eine erneute Verifizierung. Ein Schlüssel mit keys:write kann sich auch selbst über POST /keys/self/rotate rotieren; so rotiert eine Integration nach Zeitplan, ohne dass jemand die Konsole öffnet.