AccessKey
AccessKey はアプリケーションへ渡す文字列です。特定のアップストリームには紐づかず、アプリケーションがアクセスできるリソース、接続元、使用可能量だけを定義します。
それは何を管理するか§
Groupはアップストリームに接続し、AccessKeyはアプリケーションを認可します。アプリケーションは1つのキーを受け取り、その背後のGroupやアップストリーム認証情報を知る必要はありません。
1つの AccessKey で4種類の境界を定義します：
- リソース範囲——利用できる Group とクライアントから見えるモデル
- プロトコル範囲——利用できるクライアントプロトコル
- アクセス条件——許可する送信元 IP/CIDR と有効期限
- 使用量の境界 — 毎分のリクエスト数、同時実行数上限、コスト上限
この分離により、アプリケーションごとに別のキーを発行することが容易になります。各キーの上限と失効は独立しており、互いに影響しません。
有効かつ期限内のアクセスキーはこのインスタンスにログインし、自身のホーム概要、モデル、使用量、リクエストログを閲覧できます。記録が有効な場合、そのキーの元のリクエスト本文も閲覧できます。グループ、アクセスキー、実行時設定の変更や、上流の認証情報の閲覧はできません。
1つのキーを作成§
キーは任意の値またはランダム生成を使えます。空欄なら新規作成時はシステムが生成し、編集時は現在の値を維持します。ランダム生成は下書きだけを更新し、保存後に有効になります。
AccessKey → 新規作成を開き、利用可能なGroupとプロトコルを選び、必要な上限を設定して保存するとキーが生成されます。
作成後のキーはデフォルトでマスク表示されます。必要な場合だけ明示的に完全な値を表示してください。
キーはアプリケーションがゲートウェイへアクセスする唯一の認証情報です。リポジトリへコミットしたり、ログや公開 Issue に記載したりしないでください。また、複数のアプリケーションで同じキーを共有しないでください。個別に失効できなくなります。
リクエスト内容記録は既定でオフで、アクセスキーごとに有効にします。全体スイッチはありません。管理者がキーの作成・編集画面で「リクエスト内容を記録」を有効にし、プライバシーの確認後に保存します。既存キーも既定ではオフのままです。
記録には会話、ツール引数、画像データ、個人情報、キーが含まれる可能性があります。記録する権限があり、調査に必要な場合だけ有効にし、終了後は無効にしてください。API のみの利用者には別途通知してください。キーの所持者は管理画面で継続的な通知を受け、記録内容も閲覧できます。無効化しても保存済みの履歴は削除されません。
権限範囲§
1つの AccessKey で複数の Group を許可し、さらにクライアントから見えるモデル名で絞り込めます。リクエストを受け取ると、ゲートウェイはリクエスト内のモデル名とGroupの健全性に応じて、実際に使うGroupを決めます。
これにより、次の2つの使い方ができます：
- 同じモデルで複数のソース — 2つのGroupが同じモデルを公開していれば、一方が利用できないときに自動で他方を使います。アプリケーションの変更は不要です。
- 必要に応じて絞り込む——アプリケーションが本当に必要とする Group とモデルだけを許可し、他のリソースを誤って使用しないようにします
Group、プロトコル、モデルの一覧を空欄にすると、その次元は制限されません。複数の値を設定した場合は、いずれか1つに一致すればよく、異なる次元の条件はすべて同時に満たす必要があります。
プロトコル選択§
このAccessKeyに許可するクライアントプロトコルを選択します。未選択のプロトコルによるリクエストは拒否されます。
- OpenAI Chat Completions — 最も互換性が広く、多くの互換クライアントが使います。
- OpenAI Responses — ステートフルリクエストに対応する新しい API 形式です。
- Anthropic Messages — Claude Code などのクライアント向けネイティブエンドポイントです。
- Gemini — Gemini クライアント向けネイティブエンドポイントです。
迷った場合は、アプリケーションが実際に使うプロトコルをすべて選択します。機能差はプロトコルと変換境界を参照してください。
送信元と有効期限§
AccessKey には、さらに2つの認証条件を設定できます：
- 送信元 IP/CIDR——空欄なら送信元を制限しません。設定すると、一致する IPv4、IPv6、CIDR だけを許可します
- 有効期限——無期限または将来の日時を指定できます。期限切れになると、新しいリクエストと読み取り専用管理画面へのログインは拒否されます
送信元制限は GPT-Load へ直接接続したアドレスと照合し、X-Forwarded-ForやX-Real-IPは参照しません。リバースプロキシ経由の場合は、通常、エンドユーザーのアドレスではなくプロキシサーバーのアドレスを許可します。
レート制限§
毎分リクエスト数（RPM）でAccessKeyの呼び出し頻度を制限します。超過したリクエストは拒否され、空欄または0は無制限です。
目的は1つのアプリケーションの暴走を防ぐことです。たとえばスクリプトの誤ったループで、すべてのアップストリームクォータを消費する事態を防ぎます。
「同時実行数の上限」は、このキーで複数 Group にまたがって処理するリクエスト数を制限します。空欄はシステムのデフォルトを継承し、0 はキー固有の制限を解除します。全体と Group の上限は引き続き適用されます。
コスト上限§
ゲートウェイが計算した推定コストで後続リクエストを制限し、二種類のルールに対応します：
- 総額上限——累積推定コストがしきい値に達すると後続リクエストを拒否し、リセットされません。外部協力者へ渡す一回限りのキーに適しています
- サイクル制限 — 周期ごとにリセットします。周期は1分から1年まで設定でき、日次または月次が一般的です。
コスト上限には、GroupとAccessKeyの価格倍率を適用した最終コストが累積されます。どちらの倍率もデフォルトは1です。
ゲートウェイはリクエスト完了後に推定コストを上限へ加算します。大きな単一リクエストや許可済みの並行リクエストはしきい値を超える可能性があり、価格や使用量データがないリクエストは加算されません。事故防止向けであり、プロバイダー請求書や厳密な財務上限ではありません。
無効化とローテーション§
キーには有効化 / 無効化の2状態があります。無効化は即時に反映されますが設定は残り、後から再度有効化できます。アプリケーションの問題調査に便利です。
キー編集で新しい値を入力または生成し、保存すると交換できます。元のID、権限、制限と使用済み金額を維持します。保存成功後は旧キーが直ちに無効になりますが、開始済みのリクエストには影響しません。2つのキーの猶予期間はありません。
無停止ローテーションが必要な場合は、2つ目の AccessKey を新規作成してアプリケーションを更新・検証した後、古い AccessKey を無効化または削除してください。
推奨事項§
- アプリケーションごとに1つのキーを使います。共有すると利用者を区別できず、個別に失効させることもできません。
- テスト環境には別のキーを発行し、低いコスト上限を設定します。デバッグ中の予期しないループはクォータを急速に消費します。
- 必要な範囲だけを認可します。読み取り専用のデモに、高価なモデルを含むGroupへのアクセスは不要です。
- 外部または一時的なアプリケーションには、送信元制限と有効期限を設定してください。漏えい後に悪用できる範囲を小さくできます
- 外部向けのキーには総コスト上限を設定します。総額上限の方が周期上限より制御しやすくなります。