Uwierzytelnianie
Jeden typ poświadczenia i sposoby, na jakie żądanie zostaje odrzucone.
Nagłówek
Bazowy adres URL to api.openemail.uk. Każde żądanie niesie klucz w nagłówku Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Nic innego tutaj nie uwierzytelnia. Ciasteczko sesji i token sesji są odrzucane z invalid_credential_type, które nazywa poświadczenie do wysłania, zamiast zostawiać Cię ze zgadywaniem przy gołym 401.
Sprawdzanie, czy klucz działa
GET /ping to test dymny: nie wymaga żadnego uprawnienia i mówi, czym jest klucz.
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"}Jeśli to działa, a coś innego zwraca 401, problemem jest uprawnienie, a nie klucz.
scopes to lista EFEKTYWNA i jedyna, która cokolwiek autoryzuje. grantedScopes to zakres, z jakim klucz wydano; obie różnią się tylko wtedy, gdy rola ogranicza klucz. To przecięcie wyjaśnia strona Uprawnienia. roleId równe null oznacza brak pułapu, czyli najszerszy zakres, jaki klucz może mieć.
Sprawdzanie, z jakich adresów klucz może wysyłać
GET /addresses to odpowiedź na 403, którego się nie spodziewałeś.
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 ma trzy przyczyny: adres jest wyłączony, zakres wysyłki klucza go pomija (ani jego domena, ani sam adres nie są na kluczu) albo domena nie potrafi jeszcze podpisywać. enabled na adresie i sendingVerified na jego domenie pozwalają je odróżnić i na tym ten endpoint oszczędza najwięcej czasu przy diagnozie. Domena może być zweryfikowana do odbioru i nadal nie móc wysyłać.
unrestricted: true oznacza, że akceptowana jest każda część lokalna na zweryfikowanej domenie, także taka, której jeszcze nikt nie utworzył.
Jak klucz zostaje odrzucony
| Kod | Znaczenie |
|---|---|
| missing_api_key | W ogóle brak nagłówka Authorization. |
| invalid_credential_type | Ciasteczko albo token sesji. Wyślij klucz API. |
| invalid_api_key | To nie jest klucz przez nas wydany albo sekret się nie zgadza. |
| revoked_api_key | Wydany tutaj, potem unieważniony. Rozróżniany celowo. To różnica między pięciominutową poprawką a całym popołudniem. |
| expired_api_key | Wydany tutaj, potem wygasł. |
| insufficient_scope | Prawdziwy klucz, bez uprawnienia, którego wymaga ten endpoint. |
Unieważnienie działa od następnego wywołania. Wiersz zostaje potem na stronie kluczy, więc nadal widać, czy cokolwiek używało klucza w chwili jego wyłączenia. Najbardziej przydatny stan na tym ekranie to „nigdy nie użyty”, bo po nim odróżnia się wyciekły klucz od żywej zależności.
Rotacja to drugi sposób na wycofanie sekretu. Wybija nowy sekret dla tego samego klucza, więc id, nazwa, uprawnienia, rola, zakres wysyłki oraz wszystkie wiersze żądań i aktywności trwają dalej; zmienia się tylko sekret. Stary przestaje działać w chwili zakończenia rotacji, bez okna zachodzenia, a zastępujący go pokazywany jest jeden raz. W konsoli znajduje się w tym samym menu co Unieważnij i najpierw prosi o ponowną weryfikację. Klucz z keys:write może też zrotować sam siebie przez POST /keys/self/rotate — tak integracja rotuje według harmonogramu, bez otwierania konsoli przez kogokolwiek.