Аутентификация
Один тип учётных данных и способы, которыми запрос отклоняется.
Заголовок
Базовый URL — api.openemail.uk. Каждый запрос передаёт ключ в заголовке Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Ничто другое здесь не аутентифицирует. И сессионная cookie, и сессионный токен отклоняются с invalid_credential_type, который называет, какие учётные данные отправить вместо них, а не оставляет вас гадать над голым 401.
Проверка работоспособности ключа
GET /ping — проверка «на дым»: ему не нужен ни один scope, и он сообщает, что за ключ вы прислали.
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"}Если это работает, а что-то другое отвечает 401, проблема в scope, а не в ключе.
scopes — это ДЕЙСТВУЮЩИЙ список и единственный, который что-либо разрешает. grantedScopes — то, с чем ключ был выпущен, и расходятся они только тогда, когда роль ограничивает ключ сверху. Страница Scopes объясняет это пересечение. roleId, равный null, означает отсутствие потолка — это самый широкий вариант для ключа.
Посмотреть, от каких адресов может отправлять ключ
GET /addresses — это ответ на неожиданный 403.
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 имеет три причины: адрес выключен, send-scope ключа его не охватывает (на ключе нет ни его домена, ни самого адреса), либо домен пока не может подписывать. enabled у адреса и sendingVerified у его домена позволяют их различить, и именно на этом данный эндпоинт экономит бóльшую часть времени отладки. Домен может быть верифицирован для приёма и всё равно не иметь возможности отправлять.
unrestricted: true означает, что принимается любая локальная часть на верифицированном домене, включая те, которые ещё никто не создавал.
Как ключ отклоняется
| Код | Значение |
|---|---|
| missing_api_key | Заголовка Authorization нет вовсе. |
| invalid_credential_type | Cookie или сессионный токен. Отправьте API-ключ. |
| invalid_api_key | Это не выпущенный нами ключ, либо секрет не совпадает. |
| revoked_api_key | Выпущен здесь, затем отозван. Выделено отдельно намеренно. Это разница между пятиминутным исправлением и половиной дня. |
| expired_api_key | Выпущен здесь, затем истёк. |
| insufficient_scope | Настоящий ключ, но без scope, который нужен этому эндпоинту. |
Отзыв вступает в силу со следующего вызова. Строка после этого остаётся на странице ключей, поэтому вы по-прежнему можете понять, пользовалось ли что-нибудь ключом в момент, когда вы его убили. Самое полезное состояние на этом экране — «никогда не использовался», потому что именно так утёкший ключ отличают от живой зависимости.
Ротация — второй способ вывести секрет из обращения. Она выпускает новый секрет для того же ключа, поэтому id, имя, scope-ы, роль, send-scope, а также все записи запросов и активности сохраняются; меняется только секрет. Старый перестаёт работать в тот же миг, когда ротация завершается, без окна пересечения, а замена показывается один раз. В консоли она лежит в том же меню, что и Revoke, и сначала просит пройти повторную проверку. Ключ с keys:write может ротировать сам себя через POST /keys/self/rotate — так интеграция ротируется по расписанию, и никому не нужно открывать консоль.