ドキュメント本文へスキップ
API

認証

認証情報の種類は 1 つだけです。そして、リクエストが拒否されるパターンについて。

キーが有効か確認する

GET /ping は動作確認用です。スコープは不要で、そのキーが何であるかを教えてくれます。

curl
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
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 には 3 つの原因があります。アドレスが無効になっている、キーの送信スコープがそのアドレスを含んでいない（アドレス自体もそのドメインもキーに載っていない）、あるいはドメインがまだ署名できない、のいずれかです。これらを見分けるのがアドレスの enabled とドメインの sendingVerified であり、このエンドポイントが節約してくれるデバッグ時間の大半はここにあります。ドメインが受信について検証済みでも、送信できないことはあります。

unrestricted: true は、検証済みドメイン上の任意のローカルパートが受け付けられることを意味します。まだ誰も作っていないものも含みます。

キーが拒否される仕組み

コード意味
missing_api_keyAuthorization ヘッダーがまったくありません。
invalid_credential_typecookie またはセッショントークンです。API キーを送ってください。
invalid_api_key当方が発行したキーではないか、シークレットが一致しません。
revoked_api_keyここで発行された後、失効させられました。意図的に区別しています。5 分で済む修正と半日かかる調査の違いになります。
expired_api_keyここで発行された後、有効期限が切れました。
insufficient_scope有効なキーですが、このエンドポイントに必要なスコープがありません。

失効は次の呼び出しから効きます。その後もキーの一覧ページに行は残るので、停止した時点で何かがそのキーを使っていたかどうかを後から確認できます。この画面で最も役に立つ状態は「未使用」です。漏洩したキーと、稼働中の依存関係とを見分けられるからです。

ローテーションは、シークレットを退役させるもう 1 つの方法です。同じキーに対して新しいシークレットを発行するので、id、名前、スコープ、ロール、送信スコープ、そしてすべてのリクエスト行とアクティビティ行はそのまま引き継がれ、変わるのはシークレットだけです。古いシークレットはローテーション完了と同時に使えなくなり、重複期間はありません。新しいシークレットは一度だけ表示されます。コンソールでは Revoke と同じメニューにあり、先に再認証を求められます。keys:write を持つキーは POST /keys/self/rotate で自分自身をローテーションすることもでき、これによりインテグレーションは誰もコンソールを開かずに定期的なローテーションを行えます。