Autenticació
Un sol tipus de credencial, i les maneres com es rebutja una sol·licitud.
La capçalera
L'URL base és api.openemail.uk. Cada sol·licitud porta la clau en una capçalera Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Aquí no autentica res més. Una galeta de sessió i un testimoni de sessió es rebutgen tots dos amb invalid_credential_type, que anomena la credencial que cal enviar en comptes de deixar-te endevinar amb un 401 pelat.
Comprovar que una clau funciona
GET /ping és la prova de fum: no necessita cap àmbit i et diu què és la clau.
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 això funciona i una altra cosa fa 401, el problema és l'àmbit, no la clau.
scopes és la llista EFECTIVA i l'única que autoritza res. grantedScopes és allò amb què es va emetre la clau, i totes dues difereixen només quan un rol limita la clau. La pàgina d'àmbits explica aquesta intersecció. Un roleId a null vol dir que no hi ha sostre, que és el màxim d'ample que arriba a ser una clau.
Veure com pot enviar una clau
GET /addresses és la resposta a un 403 que no esperaves.
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 té tres causes: l'adreça està desactivada, l'àmbit d'enviament de la clau la deixa fora (ni el seu domini ni l'adreça mateixa són a la clau), o el domini encara no pot signar. enabled a l'adreça i sendingVerified al seu domini distingeixen els casos, i això és la major part del temps de depuració que estalvia aquest endpoint. Un domini pot estar verificat per rebre i tot i així no poder enviar.
unrestricted: true vol dir que s'accepta qualsevol part local d'un domini verificat, incloses les que encara no ha creat ningú.
Com es rebutja una clau
| Codi | Significa |
|---|---|
| missing_api_key | Cap capçalera Authorization. |
| invalid_credential_type | Una galeta o un testimoni de sessió. Envia una clau d'API. |
| invalid_api_key | No és una clau que hàgim emès, o el secret no coincideix. |
| revoked_api_key | Emesa aquí i després revocada. Diferenciada a propòsit. És la diferència entre una solució de cinc minuts i una tarda sencera. |
| expired_api_key | Emesa aquí i després caducada. |
| insufficient_scope | Una clau real, sense l'àmbit que necessita aquest endpoint. |
Revocar té efecte a la crida següent. La fila es queda a la pàgina de claus després, de manera que encara pots saber si alguna cosa feia servir la clau quan la vas matar. L'estat més útil d'aquella pantalla és "mai utilitzada", perquè és com es distingeix una clau filtrada d'una dependència viva.
Rotar és l'altra manera de retirar un secret. Encunya un secret nou per a la mateixa clau, de manera que l'id, el nom, els àmbits, el rol, l'àmbit d'enviament i totes les files de sol·licituds i d'activitat continuen; només canvia el secret. L'antic deixa de funcionar a l'instant en què acaba la rotació, sense finestra de solapament, i el reemplaçament es mostra una sola vegada. Des de la consola és al mateix menú que Revoca i et demana tornar-te a verificar abans. Una clau amb keys:write també es pot rotar a si mateixa amb POST /keys/self/rotate, que és com una integració rota segons un calendari sense que ningú obri la consola.