Authenticatie
Eén soort credential, en de manieren waarop een verzoek wordt geweigerd.
De header
De basis-URL is api.openemail.uk. Elk verzoek draagt de sleutel mee in een Authorization-header.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Niets anders authenticeert hier. Een sessiecookie en een sessietoken worden allebei geweigerd met invalid_credential_type, dat benoemt welke credential je in plaats daarvan moet sturen in plaats van je te laten gissen bij een kale 401.
Controleren of een sleutel werkt
GET /ping is de rooktest: er is geen scope voor nodig en hij vertelt je wat de sleutel is.
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"}Als dit werkt en iets anders een 401 geeft, ligt het aan de scope, niet aan de sleutel.
scopes is de EFFECTIEVE lijst en de enige die iets autoriseert. grantedScopes is waarmee de sleutel is uitgegeven, en de twee verschillen alleen wanneer een rol de sleutel begrenst. De pagina Scopes legt die doorsnede uit. Een roleId van null betekent geen plafond, en dat is het ruimst wat een sleutel krijgt.
Bekijken als wie een sleutel mag verzenden
GET /addresses is het antwoord op een 403 die je niet had verwacht.
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 heeft drie oorzaken: het adres staat uit, de verzendscope van de sleutel laat het weg (noch het domein noch het adres zelf staat op de sleutel), of het domein kan nog niet ondertekenen. enabled op het adres en sendingVerified op het domein houden die uit elkaar, en daar zit het meeste van de debugtijd die dit endpoint bespaart. Een domein kan geverifieerd zijn voor ontvangst en toch niet kunnen verzenden.
unrestricted: true betekent dat elk local-part op een geverifieerd domein wordt geaccepteerd, ook die nog niemand heeft aangemaakt.
Hoe een sleutel wordt geweigerd
| Code | Betekent |
|---|---|
| missing_api_key | Helemaal geen Authorization-header. |
| invalid_credential_type | Een cookie of een sessietoken. Stuur een API-sleutel. |
| invalid_api_key | Geen sleutel die wij hebben uitgegeven, of het secret komt niet overeen. |
| revoked_api_key | Hier uitgegeven en daarna ingetrokken. Bewust een aparte code. Het is het verschil tussen een oplossing van vijf minuten en een hele middag. |
| expired_api_key | Hier uitgegeven en daarna verlopen. |
| insufficient_scope | Een echte sleutel, zonder de scope die dit endpoint nodig heeft. |
Intrekken gaat in bij de volgende aanroep. De rij blijft daarna op de sleutelpagina staan, zodat je nog kunt zien of er iets gebruikmaakte van de sleutel toen je hem afsloot. De nuttigste status op dat scherm is "nooit gebruikt", want zo onderscheid je een gelekte sleutel van een levende afhankelijkheid.
Roteren is de andere manier om een secret uit dienst te nemen. Het slaat een nieuw secret voor dezelfde sleutel, dus de id, de naam, de scopes, de rol, de verzendscope en elke verzoek- en activiteitsrij blijven bestaan; alleen het secret verandert. Het oude werkt niet meer op het moment dat de rotatie klaar is, zonder overlapvenster, en de vervanger wordt één keer getoond. In de console staat het in hetzelfde menu als Revoke en word je eerst om herverificatie gevraagd. Een sleutel met keys:write kan ook zichzelf roteren met POST /keys/self/rotate, en zo roteert een integratie volgens schema zonder dat iemand de console opent.