API キー

GET /keys は呼び出し元が見られるすべてのキーを新しい順に 1 ページずつ一覧し、ステータス、スコープ、ロール、送信範囲、最終使用日時、作成者と最終変更者を返す。GET /keys/{id} は 1 件を読む。読み取りでシークレットが返ることはなく、2 つのキーを見分けるには maskedKey で足りる。どちらも keys:read が必要。

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys はキーを作成し、そのシークレットを token で一度だけ返す。省略した場合、スコープは emails:send、ロール・送信範囲・有効期限は呼び出し元のものになる。
• —PATCH /keys/{id} はキーの名前を変え、スコープや送信範囲を置き換え、enabled で無効化と有効化を行う。無効化は元に戻せる選択で、キーはすべてを保持し、再び有効にされるまで inactive_api_key で拒否される。
• —POST /keys/{id}/rotate はキーに新しいシークレットを与え、一度だけ返す。古いシークレットは呼び出しが戻った瞬間に使えなくなる。
• —POST /keys/{id}/revoke はキーを永久に失効させる。reason は任意。その後 DELETE /keys/{id} で一覧から取り除き、履歴は残す。
• —いずれも keys:manage が必要。呼び出し元のキー自身のローテーションは、POST /keys/self/rotate と同じく keys:write でもできる。

すべての変更は、それを行うキーと照合される。どれか 1 つの軸でも呼び出し元の外に出るキーは 403 beyond_caller_authority で拒否され、param がその軸を示す:

• —スコープ: 呼び出し元が自身のロールで絞り込まれたあとに持っているものだけ。
• —ロール: ロールで上限を課された呼び出し元は、同じロールで上限を課されたキーしか作成・管理できない。
• —有効期限: 期限のある呼び出し元は、それより後に期限が切れないキーしか作成・管理できない。
• —モード: テストキーはテストキーにしか届かない。
• —送信範囲: 呼び出し元自身の範囲内にあるドメインとアドレスだけ。1 アドレスを持っていても、そのドメイン全体を持つことにはならない。

コンソールは、キーを作成またはローテーションする前に再認証を求める。キーによる呼び出しにはそれを求められないため、keys:manage は資格情報を生み出す資格情報である。これを持つキーが漏洩すると、自身の範囲内で独自のキーを作成でき、それらは漏洩したキーを失効させたあとも動き続ける。

• —keys:manage はキーの発行を仕事とする自動化にだけ与え、メールを送るキーには決して与えない。
• —そのキーを絞り込む: ロール、送信範囲、有効期限。それが作るものはすべて 3 つを引き継ぎ、決して超えられない。
• —GET /keys/activity を見守る。それが作成・変更・失効させたキーはすべて名前付きで記録されるので、漏洩は予期しないキーとして現れる。
• —keys:read は IP アドレスとユーザーエージェントを含むリクエストログを公開する。監査用のアクセスとして扱うこと。

GET /keys/requests と GET /keys/{id}/requests は、キーが行った認証済みの呼び出しをすべて新しい順に読む: メソッド、パス、ステータス、エラーコード、所要時間、IP、ユーザーエージェント。本文やクエリ文字列は含まない。keyIds、failedOnly、since、until はコンソールと同じフィルターである。GET /keys/activity と GET /keys/{id}/activity はキーに起きたことを読み、actor が実行者を @username または API key <name> として示す。何も削除されず、削除されたキーも履歴を保つ。