AIゲートウェイの仮想キー（Virtual Key）
仮想キー（Virtual Key）は、AIゲートウェイが発行する、ゲートウェイのプロキシエンドポイントにアクセスするための認証情報です。仮想キーをアプリやAIツールに発行し、実際のプロバイダーAPIキーはゲートウェイ側にのみ保存します。これにより、実際のキーがあちこちに散らばるのを防ぎつつ、仮想キーごとに権限付与、レート制限、ローテーション、失効を個別に行えます。本記事では仮想キーのライフサイクル管理全体について説明します。
仮想キーを使う理由
- 実キーの保護 — アプリとツールは仮想キーのみに触れ、プロバイダーの実キーは外部に漏れません。
- 用途別の権限細分化 — プロジェクト／ツールごとに異なる仮想キーを作成し、それぞれ利用可能なモデル、チャネル、レートを制限できます。
- いつでも取り消し可能 — あるキーが漏洩したり不要になったりした場合、他のキーに影響を与えずに失効またはローテーションできます。
前提条件
- ServBayアカウントにログイン済みであること。
- チャネルページで少なくとも1つの利用可能なチャネルを追加済みであること。
仮想キーの作成
AIゲートウェイ → キー（Keys） ページに移動し、作成（Create） をクリックします：
- 名前 — そのキーの用途を識別するため（例：
claude-code、my-app-dev）。 - 説明（任意） — 補足説明。
- 有効期限 — 無期限、または指定日を設定できます。
- 許可するチャネル（任意） — タグの複数選択で、そのキーが指定したチャネルにのみルーティングされるよう制限します。空欄の場合は制限なし。
- 許可するモデル（任意） — そのキーが指定したモデルのみを呼び出せるよう制限します。空欄の場合は制限なし。
- レート制限（任意）：
- RPM / TPM — 1分あたりのリクエスト数／トークン数の上限。
- RPD / TPD — 1日あたりのリクエスト数／トークン数の上限。
平文はいつでも取得可能
キーの作成に成功すると、ゲートウェイは平文キー（servbay-sk-xxxxxxxx...の形式）を表示します。ゲートウェイは平文をローカルに保存し、後からキーの詳細でも取得できます。初期にハッシュ方式で作成された履歴キーのみ、復元可能な平文がありません（取得リクエスト時に409を返します）。キーの漏洩が疑われる場合は、直接「ローテーション」を実行してください。
キー一覧
キー一覧には、各仮想キーの以下が表示されます：
- プレフィックス —
servbay-sk-abcd...など、識別用。 - ステータス — 有効（active）、失効済み（revoked）、期限切れ（expired）。
- 作成日時／最終使用日時。
- 権限タグ — 許可するモデル／チャネル、レート制限。
キーの管理
キー一覧では、各キーに対して以下の操作を実行できます：
| 操作 | 説明 | 影響 |
|---|---|---|
| 編集（Edit） | 名前、説明、許可するモデル／チャネル、レート制限を変更 | 即時反映、キー自体は不変 |
| ローテーション（Renew） | 平文を再生成し、旧平文は即時無効化、新平文はいつでも取得可能 | そのキーを使用するすべてのアプリとツールを更新する必要あり |
| 失効（Revoke） | キーを即時無効化するが、監査記録は保持 | 復元不可；そのキーを使ったリクエストは拒否される |
| 削除（Delete） | キーを完全に削除 | 復元不可 |
ローテーション vs 失効
- ローテーション（Renew）：キー自体は残り、新しい平文に変わるだけ——キー漏洩が疑われるが、同じキー設定を使い続けたい場面に適しています。利用側の更新を忘れずに。
- 失効（Revoke）：キーを永久に無効化するが記録は保持し、監査しやすくする——あるキーが不要になったことが確認できた場面に適しています。 ローテーションと失効はどちらも二次確認が求められます。
ワンクリック引き継ぎとの関係
ワンクリック引き継ぎを使ってあるAIツールをゲートウェイに向けると、ゲートウェイはそのツール専用の仮想キーを自動的に作成し、ツールの設定に書き込みます。これらの自動作成されたキーは、キーページで手動管理することもできます。
よくある質問（FAQ）
- Q：平文キーをコピーし忘れた場合はどうすればよいですか？
- A：キーの詳細で平文を取得できます。初期にハッシュ方式で作成された履歴キーのみ取得できません。その場合は「ローテーション」を実行してください。
- Q：失効と削除の違いは何ですか？
- A：失効はキーの記録を保持し（監査用）、削除は完全に消去します。どちらもキーは即座に無効になります。
- Q：「許可するモデル」を制限した後、アプリが他のモデルをリクエストするとどうなりますか？
- A：ゲートウェイはそのキーの権限外のモデルリクエストを拒否します。アプリが使用するモデルが許可リストに含まれていることを確認するか、制限を解除してください。
- Q：レート制限が発動するとどうなりますか？
- A：RPM/TPM/RPD/TPDを超えたリクエストはゲートウェイによって制限されます。統計ページで実際の使用量を確認してから上限を調整できます。
まとめ
仮想キーを使えば、最小権限で取り消し可能な方法でAI機能をアプリやツールに提供できます。許可モデル／チャネルの制限とレート制限を組み合わせることで、各ユースケースに合わせた認証情報をカスタマイズし、必要なときにいつでもローテーションまたは失効でき、実際のプロバイダーAPIキーに触れる必要はありません。
