인증
자격 증명은 한 종류뿐이며, 요청이 거부되는 방식들입니다.
헤더
기본 URL은 api.openemail.uk입니다. 모든 요청은 Authorization 헤더에 키를 담아 보냅니다.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…그 밖에는 어떤 것도 인증 수단이 되지 않습니다. 세션 쿠키와 세션 토큰은 모두 invalid_credential_type으로 거부되는데, 이 코드는 맨 401만 던져 놓고 추측하게 만드는 대신 어떤 자격 증명을 보내야 하는지 알려 줍니다.
키가 동작하는지 확인하기
GET /ping이 기본 점검용입니다. 아무 스코프도 필요 없고 키가 무엇인지 알려 줍니다.
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이 난다면 문제는 키가 아니라 스코프입니다.
scopes는 실제로 적용되는 목록이며, 무언가를 인가하는 것은 이 목록뿐입니다. grantedScopes는 키를 발급할 때 부여한 목록이고, 둘은 역할이 키에 상한을 걸 때만 달라집니다. 이 교집합은 스코프 페이지에서 설명합니다. roleId가 null이면 상한이 없다는 뜻이고, 이것이 키가 가질 수 있는 가장 넓은 범위입니다.
키가 어떤 주소로 보낼 수 있는지 확인하기
예상치 못한 403에 대한 답은 GET /addresses입니다.
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의 원인은 세 가지입니다. 주소가 꺼져 있거나, 키의 발송 범위에서 그 주소가 빠져 있거나(도메인도 주소 자체도 키에 없음), 도메인이 아직 서명할 수 없는 경우입니다. 주소의 enabled와 그 도메인의 sendingVerified가 이를 구분해 주며, 이 엔드포인트가 아껴 주는 디버깅 시간의 대부분이 여기에 있습니다. 도메인이 수신은 검증되었으면서 발송은 불가능할 수 있습니다.
unrestricted: true는 검증된 도메인의 어떤 로컬 파트든, 아직 아무도 만들지 않은 것까지 포함해 받아들인다는 뜻입니다.
키가 거부되는 방식
| 코드 | 의미 |
|---|---|
| missing_api_key | Authorization 헤더가 아예 없습니다. |
| invalid_credential_type | 쿠키나 세션 토큰입니다. API 키를 보내세요. |
| invalid_api_key | 여기서 발급한 키가 아니거나, 시크릿이 일치하지 않습니다. |
| revoked_api_key | 여기서 발급한 뒤 폐기된 키입니다. 일부러 구분해 두었습니다. 5분이면 끝날 일과 오후 내내 걸릴 일의 차이입니다. |
| expired_api_key | 여기서 발급한 뒤 만료된 키입니다. |
| insufficient_scope | 유효한 키이지만 이 엔드포인트에 필요한 스코프가 없습니다. |
폐기는 다음 호출부터 적용됩니다. 그 뒤에도 행은 키 페이지에 남으므로, 키를 죽였을 때 무언가가 그 키를 쓰고 있었는지 확인할 수 있습니다. 그 화면에서 가장 유용한 상태는 "한 번도 사용 안 함"인데, 유출된 키와 살아 있는 의존성을 구분하는 방법이기 때문입니다.
시크릿을 퇴역시키는 다른 방법은 회전입니다. 같은 키에 대해 새 시크릿을 발급하므로 id, 이름, 스코프, 역할, 발송 범위, 모든 요청 및 활동 기록이 그대로 이어지고 시크릿만 바뀝니다. 기존 시크릿은 회전이 끝나는 즉시 중첩 기간 없이 동작을 멈추며, 새 시크릿은 한 번만 표시됩니다. 콘솔에서는 Revoke와 같은 메뉴에 있고 먼저 재인증을 요구합니다. keys:write를 가진 키는 POST /keys/self/rotate로 스스로 회전할 수도 있는데, 아무도 콘솔을 열지 않고 연동이 정해진 주기로 회전하는 방법입니다.