ナレッジベース
API キー
用途ごとに 1 つのキー。必要なスコープと送信元だけに絞り、すべての呼び出しを記録します。
詳細
- 自分が所有するワークスペースの「設定」→「APIキー」で作成します。シークレットは一度だけ表示され、キーはすべて oe_live_ キーです。
- キーが持つのは選んだスコープだけで、新しいキーは emails:send から始まります。ロールを付けることもでき、それは 2 つ目の権限付与ではなく上限です。GET /ping はキーが指定したスコープと、ロールが残したスコープを返すので、キーが明らかに持つスコープで 403 になっても原因が見えます。
- 送信範囲にはドメイン単位で最大 25 件、アドレス単位で最大 50 件を指定できます。ドメイン指定は後から追加したアドレスも対象で、リスト外の送信元は 403 で拒否されます。
- 任意の有効期限を設定すると、キーは最長 10 年先で自動的に失効します。
- ローテーションで変わるのはシークレットだけです。ID、スコープ、送信範囲、リクエスト履歴は引き継がれ、古いシークレットは新しいものを作った瞬間に使えなくなります。keys:write を持つキーは API で自分自身をローテーションできます。失効は削除ではなく更新なので、以降の呼び出しには revoked_api_key が返ります。
- 認証済みの呼び出しはすべて、メソッド、パス、ステータス、エラーコード、所要時間、IP、ユーザーエージェントとともに記録され、本文やクエリ文字列は記録しません。キーのページでは分析、アクティビティ、リクエストとして表示され、よく使われるルート、失敗の頻度、中央値のレイテンシがわかり、同じ画面で複数のキーをまとめて見られます。ログは削らずに保持します。
- このページでできることは、すべて API と SDK でもできる。GET /keys と GET /keys/{id} はシークレットを除いたキーを読み取り、POST /keys はキーを作成し、PATCH /keys/{id} は名前の変更、スコープや送信範囲の変更、無効化と再有効化を行い、rotate、revoke、delete は名前のとおりの動作をする。リクエストログとアクティビティも同じように、1 つのキーでもすべてのキーでも、このページと同じフィルターで読める。読み取りには keys:read、変更には keys:manage が必要で、どちらも誰かが付与しない限りどのキーも持っていない。MCP サーバーもログとアクティビティを listApiKeyRequests と listApiKeyActivity として読める。
- キーが自分より広いキーを作ったり、そうしたキーに触れたりすることはない。スコープ、ロール、有効期限、モード、送信範囲のすべてが、呼び出しを行うキーの内側に収まっていなければならない。再認証はキーによる呼び出しには適用できないため、keys:manage は資格情報を生み出す資格情報である。キーを発行する自動化にだけ、専用のロール・送信範囲・有効期限とともに与え、その行動がすべて記録されるアクティビティタブを見守ること。
- 足りないもの: キーを IP アドレスに紐付けることはできず、テストモードのキーも作成できない。