Autentizace
Jediný typ přihlašovacích údajů a způsoby, jakými může být požadavek odmítnut.
Hlavička
Základní URL je api.openemail.uk. Každý požadavek nese klíč v hlavičce Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Nic jiného se zde neautentizuje. Session cookie i session token se odmítnou s invalid_credential_type, které pojmenuje, jaké přihlašovací údaje poslat místo nich, místo aby vás nechalo hádat nad holým 401.
Ověření, že klíč funguje
GET /ping je rychlá zkouška: nevyžaduje žádný scope a řekne vám, co je klíč zač.
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"}Pokud tohle funguje a něco jiného vrací 401, problém je ve scope, ne v klíči.
scopes je EFEKTIVNÍ seznam a jediný, který cokoli autorizuje. grantedScopes je to, s čím byl klíč vydán, a liší se od sebe jen tehdy, když klíč stropuje role. Ten průnik vysvětluje stránka Scopes. roleId s hodnotou null znamená žádný strop, což je to nejširší, co klíč může mít.
Zjištění, pod jakými adresami smí klíč odesílat
GET /addresses je odpověď na 403, které jste nečekali.
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 má tři příčiny: adresa je vypnutá, rozsah odesílání daného klíče ji nezahrnuje (na klíči není ani její doména, ani adresa samotná), nebo doména zatím neumí podepisovat. Rozliší je enabled u adresy a sendingVerified u její domény, a právě v tom spočívá většina času při ladění, který tento endpoint ušetří. Doména může být ověřená pro příjem a přesto nemůže odesílat.
unrestricted: true znamená, že se přijme jakákoli local-part na ověřené doméně, včetně těch, které zatím nikdo nevytvořil.
Jak je klíč odmítnut
| Kód | Význam |
|---|---|
| missing_api_key | Hlavička Authorization vůbec chybí. |
| invalid_credential_type | Cookie nebo session token. Pošlete API klíč. |
| invalid_api_key | Není to klíč, který jsme vydali, nebo nesedí secret. |
| revoked_api_key | Vydán zde, poté odvolán. Odlišeno záměrně. Je to rozdíl mezi pětiminutovou opravou a celým odpolednem. |
| expired_api_key | Vydán zde, poté vypršel. |
| insufficient_scope | Skutečný klíč, ale bez scope, který tento endpoint vyžaduje. |
Odvolání se projeví při dalším volání. Řádek poté na stránce klíčů zůstává, takže pořád poznáte, jestli klíč něco používalo ve chvíli, kdy jste ho zabili. Nejužitečnější stav na té obrazovce je „nikdy nepoužit“, protože právě podle něj se pozná uniklý klíč od živé závislosti.
Rotace je druhý způsob, jak secret vyřadit. Vyrazí nový secret pro tentýž klíč, takže id, název, scopes, role, rozsah odesílání i všechny řádky požadavků a aktivity pokračují dál; mění se jen secret. Ten starý přestane fungovat v okamžiku, kdy se rotace dokončí, bez jakéhokoli překryvného okna, a náhrada se zobrazí jen jednou. V konzoli je ve stejné nabídce jako Revoke a nejdřív po vás chce opětovné ověření. Klíč se keys:write se může také rotovat sám pomocí POST /keys/self/rotate, čímž integrace rotuje podle rozvrhu, aniž by kdokoli otevřel konzoli.