AccessKey
AccessKey はアプリケーションへ渡す文字列です。特定のアップストリームには紐づかず、アプリケーションがアクセスできるリソース、接続元、使用可能量だけを定義します。
それは何を管理するか§
Groupはアップストリームに接続し、AccessKeyはアプリケーションを認可します。アプリケーションは1つのキーを受け取り、その背後のGroupやアップストリーム認証情報を知る必要はありません。
1つの AccessKey で4種類の境界を定義します：
- リソース範囲——利用できる Group とクライアントから見えるモデル
- プロトコル範囲——利用できるクライアントプロトコル
- アクセス条件——許可する送信元 IP/CIDR と有効期限
- 使用量の境界 — 1分あたりのリクエスト数とコスト上限です。
この分離により、アプリケーションごとに別のキーを発行することが容易になります。各キーの上限と失効は独立しており、互いに影響しません。
有効かつ期限内の AccessKey では現在のインスタンスへ直接ログインできますが、自身の範囲内にあるホーム、モデル、使用量、マスキング済みリクエストログだけを参照できます。Group、AccessKey、ランタイム設定の変更や、アップストリーム認証情報の表示はできません。
1つのキーを作成§
AccessKey → 新規作成を開き、利用可能なGroupとプロトコルを選び、必要な上限を設定して保存するとキーが生成されます。
作成後のキーはデフォルトでマスク表示されます。必要な場合だけ明示的に完全な値を表示してください。
キーはアプリケーションがゲートウェイへアクセスする唯一の認証情報です。リポジトリへコミットしたり、ログや公開 Issue に記載したりしないでください。また、複数のアプリケーションで同じキーを共有しないでください。個別に失効できなくなります。
権限範囲§
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つのアプリケーションの暴走を防ぐことです。たとえばスクリプトの誤ったループで、すべてのアップストリームクォータを消費する事態を防ぎます。
コスト上限§
RPM より直接的な保護は、支出額に上限を設定することです。次の2種類のルールがあります：
- 総額 — 累積コストが上限に達すると停止し、リセットされません。外部協力者向けの一時キーに適しています。
- サイクル制限 — 周期ごとにリセットします。周期は1分から1年まで設定でき、日次または月次が一般的です。
コスト上限にはゲートウェイが算出する見積コストを使い、アップストリームのトークン使用量とモデル価格から算出します。この値はプロバイダーの請求額とは一致しません。価格データのないモデルは消費に含まれません。予期しない暴走を防ぐための保護として使い、正確な財務管理には使わないでください。集計基準は監視とトラブルシュートを参照してください。
無効化とローテーション§
キーには有効化 / 無効化の2状態があります。無効化は即時に反映されますが設定は残り、後から再度有効化できます。アプリケーションの問題調査に便利です。
管理画面のキーのローテーションでは、既存のレコード上で新しいキーを生成し、名前、権限、クォータ設定を引き継ぎます。ローテーションが成功すると古いキーは直ちに無効になりますが、すでに開始済みのリクエストには影響しません。新旧両キーを使える猶予期間はないため、漏えいを確認したキーを直ちに遮断する用途に適しています。
無停止ローテーションが必要な場合は、2つ目の AccessKey を新規作成してアプリケーションを更新・検証した後、古い AccessKey を無効化または削除してください。
推奨事項§
- アプリケーションごとに1つのキーを使います。共有すると利用者を区別できず、個別に失効させることもできません。
- テスト環境には別のキーを発行し、低いコスト上限を設定します。デバッグ中の予期しないループはクォータを急速に消費します。
- 必要な範囲だけを認可します。読み取り専用のデモに、高価なモデルを含むGroupへのアクセスは不要です。
- 外部または一時的なアプリケーションには、送信元制限と有効期限を設定してください。漏えい後に悪用できる範囲を小さくできます
- 外部向けのキーには総コスト上限を設定します。総額上限の方が周期上限より制御しやすくなります。