AI API ゲートウェイの BYOK プロバイダー キー オンボーディング: トラフィックをルーティングする前に顧客の資格情報を確認する

BYOK オンボーディングを、アップストリームの API キーを受け入れてすぐにルーティングを有効にするテキスト ボックスとして扱わないでください。実稼働 AI API ゲートウェイでは、顧客が指定した認証情報にはコントロール プレーン ワークフローが必要です。つまり、プロバイダー バインディングの収集、キーの隔離、プロバイダー固有のプローブの実行、機能マトリックスの構築を行ってから、テナント ルーティング ポリシーに認証情報を添付します。

リーダーの問題は動作可能です。顧客が有効に見える OpenAI、Anthropic、Gemini、または Azure OpenAI 資格情報を貼り付けましたが、キーが間違ったプロジェクトに属しているか、モデルへのアクセス権がないか、選択したエンドポイントを呼び出すことができないか、クォータが弱いか、請求と調整に必要な使用状況データが公開されていないため、最初の実際の要求は失敗します。ゲートウェイは、顧客のトラフィックが制約に依存する前に、それらの制約を検出する必要があります。

BYOK 認証情報をステートフル コントロール プレーン オブジェクトとして設計する

BYOK 認証情報は、アプリケーションが使用するゲートウェイ発行のキーとは別のものである必要があります。アプリケーションは安定した仮想キーを使用してゲートウェイを呼び出す必要がありますが、ゲートウェイはそのテナント、製品プラン、モデル プロファイル、およびポリシーを検証済みのアップストリーム資格情報にマッピングします。この分離により、顧客がアップストリーム キーをローテーションしたり、プロバイダー プロジェクトを変更したり、特定のモデル機能を失ったりした場合でも、アプリケーション統合の安定性が維持されます。

少なくとも、次の状態でアップストリーム認証情報をモデル化します:

• 送信済み: コントロール プレーンによって受信されましたが、まだ使用できません。
• 隔離: はコンテナーに保存され、プローブの実行中はライブ トラフィックからブロックされます。
• 検証済み: 検証に合格した特定の機能が許可されています。
• 劣化: 一部のトラフィックではまだ使用可能ですが、1 つ以上の機能、割り当てシグナル、または使用状況レポートの期待が失敗しました。
• 一時停止: 認証、権限、割り当て、請求、またはポリシーのエラーの後、一時的にブロックされました。
• rotation-required: はまだゲートウェイに認識されていますが、運用環境での使用を続ける前に置き換える必要があります。
• 取り消されました: ルーティングから削除され、フォールバックとして受け入れられなくなりました。

このステート マシンは、マルチプロバイダー LLM API ゲートウェイ を構築するチームにとって重要です。これは、単一の正規化された「有効なキー」フラグがプロバイダー固有の動作を隠すためです。ゲートウェイは、各テナントにとってどのエンドポイント、モデル、リージョン、モダリティ、レポート モードが安全であるかを認識する必要があります。

シークレットを要求する前にプロバイダー バインディング フィールドを収集します

オンボーディング フォームでは、シークレットの前またはシークレットと一緒に、非シークレットのルーティング コンテキストを要求する必要があります。このコンテキストにより、あいまいなプローブが防止され、より適切なエラー メッセージが生成されます。

OpenAI

対象の組織とプロジェクト、要求されたモデル プロファイル、キーがユーザー キーかサービス アカウント キーかを収集します。 OpenAI は組織レベルとプロジェクト レベルでのロールベースのアクセス制御を文書化し、API 権限はそのモデルによって管理されるため、有用な検証者はプロジェクトのバインディングと権限をチェックする必要があります。モデルのリストなどの呼び出しには、関連するキーとロールからのモデル読み取り権限が必要になる場合があります。

サービス アカウントの場合、スコープを独立した権限としてではなく制限として扱います。 OpenAI サービス アカウント キー スコープは、サービス アカウントが実行できる操作を制限できますが、割り当てられたプロジェクト ロール以外の権限を付与することはできません。実際には、キーのスコープが狭いように見えても、プロジェクト ロールで要求されたモデルまたはエンドポイントが許可されていないため、失敗する可能性があります。

Anthropic

顧客が複数のワークスペースを持っている場合、または ID にリンクされたフローを使用している場合は、目的のワークスペース ID を収集します。 Anthropic ワークスペースにはメンバー、サービス アカウント、API キー、リソース制限を含めることができ、一元的な請求と管理の下でプロジェクト、環境、またはチームを分離することを目的としています。

検証者は、リクエストに anthropic-workspace-id ヘッダーが必要かどうかを保存する必要があります。 Anthropic のドキュメントには、ID リンクまたはマルチワークスペースの API キー フローにはそのヘッダーが必要になる可能性があると記載されています。また、ランタイム ワークスペース スコープのキーが組織レベルのリソース制限を検査できると想定することも避けてください。ワークスペース スコープのキーは、ワークスペースのレート制限検査など、一部の組織レベルの管理者 API 操作には無効です。

Gemini

キーが AI Studio から来たのか Google Cloud プロジェクトから来たのか、対象のプロジェクト コンテキスト、許可された API、および顧客が期待する制限を収集します。 Google の Gemini API キーのドキュメントには、すべての Gemini API キーが Google Cloud プロジェクトに関連付けられており、新しい AI Studio キーが認証キーとして作成されると記載されています。また、安全でない無制限のキーからの移行の一環として、無制限の標準キーは Gemini API によって拒否されるとも述べています。

オンボーディング UI は、プローブが通過するまで顧客に制限を緩和するよう促すのではなく、安全でない制限されていない標準キーにフラグを付ける必要があります。 Google Cloud API-key ガイダンスでは、API の制限、クエリ パラメータ内のキーの回避、不要なキーの削除、キーをリポジトリにコミットしないことを推奨しています。 Gemini 認証キーは、Gemini API が Google クラウド プロジェクト リソースを作成しないため、特別な運用例外です。ただし、検証者はキーのタイプと制限の状況を記録する必要があります。

アズール OpenAI

顧客が提供できる場合は、エンドポイント、デプロイメント名、API バージョン、リージョン、およびサブスクリプション コンテキストを収集します。 Azure OpenAI は顧客が作成したデプロイメントを介してルーティングされるため、一般的なモデル名では十分ではありません。キーは、要求されたデプロイ名が見つからない、別のリージョンにある、またはゲートウェイが予期しないモデル バージョンにバインドされているにもかかわらず、リソースに対して有効である可能性があります。

Azure OpenAI の割り当ては、サブスクリプション、リージョン、モデル、デプロイメント タイプごとに TPM 単位で割り当てられます。割り当てられた TPM は展開速度制限にマップされますが、RPM も強制されます。実行時応答は、残りのリクエスト、残りのトークン、retry-after-ms などの有用なレート制限ヘッダーを公開できます。プローブおよびランタイム監視中にこれらの信号をキャプチャします。

レイヤーで検証を実行する

優れたプリフライト スイートは、安価で低リスクから開始され、顧客が同意した場合にのみ、課金対象となる最小限のプローブを 1 つ使用します。一部のプロバイダーはランタイム キーを介して十分なイントロスペクションを公開していないため、成功したオンボーディング結果には、単に合格か不合格かだけでなく、信頼レベルを含める必要があります。

1.静的チェック

プロバイダーを呼び出す前に、明らかな形式の問題、フィールドの欠落、互換性のないエンドポイントの形状、サポートされていないリージョン、不正な形式のデプロイメント名を検証してください。静的チェックでは、生のシークレットをログに記録しないでください。代わりに、フィンガープリント、作成ソース、テナント ID、プロバイダー、およびコンテナー参照を保存します。

例:

• Azure エンドポイントは、予期されたリソース URL パターンと一致しません。
• 要求されたモデル プロファイルが Azure OpenAI にマップされているにもかかわらず、Azure デプロイ名が空です。
• Anthropic マルチワークスペース オンボーディング パスのワークスペース ID がありません。
• Gemini キーは、制限が必要な場合、無制限の標準キーとしてマークされます。
• 要求されたプロファイルにはイメージ生成が含まれていますが、プロバイダー アダプターは BYOK 認証情報のそのモダリティをサポートしていません。

2.低リスク読み取りプローブ

プロバイダーが許可している場合は読み取り専用プローブを使用します。モデル リストの呼び出し、デプロイメント メタデータ チェック、またはアカウント機能エンドポイントにより、モデル出力を生成せずに、認証、プロジェクト バインディング、および権限のエラーが明らかになります。正規化された結果と生のプロバイダー ステータス コードの両方を記録します。

推奨される正規化された結果は次のとおりです:

• auth_failed: 資格情報が無効、取り消され、期限切れ、または無効になっています。
• wrong_project_or_workspace: 有効なキーですが、目的のプロジェクトまたはワークスペースにバインドされていません。
• permission_denied: 認証されましたが、エンドポイント、モデル、または管理者の権限がありません。
• model_unavailable: キーは機能しますが、要求されたモデルまたはデプロイメントは機能しません。
• quota_unknown: ランタイムは機能しますが、クォータを検査できません。
• usage_reporting_unavailable: ゲートウェイは、提供された認証情報を介してプロバイダー側の使用状況を調整できません。

3.最小限の推論プローブ

モデルをリストすることとその実行が許可されることは同じではないため、通常、要求されたモデル プロファイルごとに少なくとも 1 つの実際の推論プローブが必要です。明示的な顧客の同意を求め、プローブ予算を小さく設定し、必要な機能を実行する最も安価なエンドポイントを使用します。

プローブは決定的で退屈なものにしてください。テキスト プロファイルの場合は、出力上限を低く設定した短いプロンプトを送信します。ストリーミングの場合、プロバイダーがストリーム イベントと最終的な使用メタデータを期待どおりに返すことを確認します。ツール対応プロファイルの場合は、合成ツール定義を使用し、プロバイダーがツール スキーマを受け入れるかどうかを確認します。視覚的には、プロバイダーとポリシーが許可している場合は、小さな既知のテスト画像を使用します。機密の顧客データを保存したり、ビジネス固有のプロンプトを必要としたりするプローブは避けてください。

4.陰性検査

否定的なテストは、ポリシーの境界が現実であることを証明します。テナントが定義されたモデル プロファイルの使用のみを許可されている場合、検証者は、明らかに許可されていないモデル、エンドポイント、ツール、またはリージョンを試し、プロバイダーがそれを認識する前にゲートウェイがそれをブロックすることを確認する必要があります。これらはゲートウェイ ポリシー テストであり、プロバイダー悪用テストではありません。

これは、AI API 顧客プロビジョニング がダウンストリーム キーを自動的に作成する再販業者や SaaS のセットアップの場合に特に重要です。顧客指定のアップストリーム キーは、より広範なプロバイダー権限があるという理由だけで、テナントのゲートウェイ ポリシーをバイパスしてはなりません。

ブール値ではなく、機能マトリックスを保存します

オンボーディングの出力は、認証情報のバージョンに関連付けられた機能マトリックスである必要があります。このマトリックスは、ルーティング、サポート、請求、および顧客向けのステータス ページからクエリできる必要があります。

実際のマトリックスには次のものが含まれます:

• プロバイダー、認証情報のバージョン、ボールト参照、テナント、および環境。
• 利用可能な場合は、観察された組織、プロジェクト、ワークスペース、エンドポイント、リージョン、またはデプロイメント バインディング。
• サポートされるエンドポイント: チャット、応答、メッセージ、埋め込み、バッチ、リアルタイム、画像、音声、またはプロバイダー固有の同等のもの。
• サポートされているモデルとデプロイ名。
• サポートされているリクエスト機能: ストリーミング、ツール、JSON モード、構造化出力、ビジョン、オーディオ、プロンプト キャッシュ、バッチ ジョブ。
• 監視されたレート制限ヘッダーと再試行ヘッダー。
• 既知の割り当てソース: 管理者 API、ランタイム ヘッダー、顧客が宣言した、または不明。
• 使用状況レポート モード: プロバイダー レポートが利用可能、ゲートウェイのみの測定、部分的な調整、またはサポートされていません。
• 検証の信頼度: 深い、浅い、実行時のみ、または顧客が宣言したもの。
• 最後に成功したプローブ、最後に失敗したプローブ、および生のエラー証拠。

ルーティングはこの行列を使用する必要があります。マトリックスで、キーがテキスト推論をサポートしているがバッチ ジョブはサポートしていないことが示されている場合、ゲートウェイはテキスト トラフィックを許可し、顧客向けの明確なメッセージでバッチ トラフィックを拒否する必要があります。クォータを検査できないが、ランタイム プローブが機能する場合は、ゲートウェイがフルキャパシティを可視化しているように見せるのではなく、限定的な信頼度で認証情報を検証済みとしてマークできます。

検証結果をルーティング ポリシーにマッピングする

ゲートウェイは、「このシークレットを使用する」ために「テナントが選択したプロバイダー」から直接ルーティングしないでください。テナント ポリシーからモデル プロファイルへ、モデル プロファイルから機能要件へ、要件から対象となる資格情報のバージョンへルーティングします。

例:

tenant: acme-prod
virtual_key: mgk_live_...
model_profile: support-chat-standard
requirements:
  endpoint: chat
  provider_candidates: [openai, anthropic, azure_openai]
  features: [streaming, tools]
  max_region: customer_approved_regions
  usage_mode: gateway_metered_with_provider_reconciliation_preferred
eligible_credentials:
  - byok_openai_project_key_v3: verified, tools=true, streaming=true, usage_report=partial
  - byok_azure_openai_v2: degraded, deployment_found=true, quota_low=true
routing_decision:
  primary: byok_openai_project_key_v3
  fallback: none unless customer permits provider-managed spillover

このポリシー層は、統合 AI API 請求も保護します。ゲートウェイが単にリクエストを通過させ、後でプロバイダーの請求書を信頼する場合、BYOK は集中請求を弱める可能性があります。プロバイダー側の使用状況レポートが利用できない場合でも、ゲートウェイはテナント レベルの使用状況、リクエスト ID、モデル プロファイル、利用可能な場合は正規化されたトークン数、調整の信頼性、およびサポートされていないレポート モードを記録する必要があります。

顧客向けの言葉で障害に対処する

生のプロバイダー エラーはサポートには役立ちますが、ほとんどの顧客は直接の修復ガイダンスを必要としています。生のエラー コードとヘッダーを内部に保存し、失敗を安定したメッセージに変換します。

オンボーディング後に認証情報を再確認する

プリフライトの成功はスナップショットであり、保証されるものではありません。プロジェクトのロール、ワークスペース ポリシー、クォータ、請求状態、モデルの可用性、および地域のキャパシティは、オンボーディング後に変更される可能性があります。ゲートウェイは、スケジュールされたヘルス チェックとイベント ドリブンの再チェックを実行する必要があります。

次の後に再チェックをトリガーします:

• 401 またはプロバイダー認証の失敗。
• 403 または許可が拒否された応答。
• 404 モデル、デプロイメント、またはエンドポイントが見つからない応答。
• 429、クォータ超過、または通常のトラフィック パターン外のレート制限応答。
• プロバイダーの請求、組織、ワークスペース、またはプロジェクトのエラー。
• 顧客は、要求されたモデル プロファイル、リージョン、ツール、またはデータ ポリシーを変更します。

1 つの機能が壊れたときに、テナント全体をすぐに一時停止しないでください。ストリーミングが失敗しても非ストリーミング推論が引き続き機能する場合は、ストリーミング機能が低下しているとマークし、ポリシーが許可する場合は対象となる非ストリーミング ワークロードをルーティングします。単一の Azure デプロイメントが欠落している場合は、顧客のすべてのプロバイダー資格情報ではなく、そのデプロイメントをブロックします。

並行検証ワークフローとしてローテーションを構築

回転は盲目的な上書きであってはなりません。新しい認証情報バージョンを作成して隔離に保存し、元のオンボーディングと同じプローブを実行して、検証に合格した後にのみルーティングをアトミックに切り替えます。顧客が明示的に許可し、ポリシーで継続的な保管が許可されている場合にのみ、短いロールバック期間内に古いキーを保持します。

安全なローテーションのワークフローは次のようになります:

1. 顧客は交換用の資格情報とバインディング フィールドを送信します。
2. ゲートウェイはシークレットを新しい認証情報バージョンとして隔離に保存します。
3. Verifier は静的チェック、読み取りプローブ、推論プローブ、ポリシー テストを実行します。
4. 機能マトリックスはアクティブなバージョンと比較されます。
5. お客様は、バッチ サポートの欠如や割り当ての信頼性の低下などの回帰を認識します。
6. ゲートウェイは、1 回のコントロール プレーンの更新でルーティングを新しいバージョンに切り替えます。
7. 古いバージョンはすぐに取り消されるか、短い明示的なロールバック期間だけ保持されます。

比較ステップは重要です。ベース テキスト モデルを呼び出すことができる置換キーは、ツールのサポート、使用状況レポート、地域割り当て、または運用環境へのアクセスを失った場合、依然として回帰である可能性があります。

明示すべきトレードオフ

検証によってプロバイダ料金が少額になる可能性があります。 同意を求め、最大のプローブ予算を示し、最小限のプロンプトと出力上限を使用することをお勧めします。 「検証」内に課金対象のプローブを非表示にしないでください。

管理者のイントロスペクションにより信頼性は向上しますが、影響範囲は拡大します。 一部のお客様は、より詳細な検証のために管理者またはレポートの資格情報を提供します。ランタイムキーのみを提供するものもあります。両方をサポートしますが、結果として生じる信頼度には明確にラベルを付けます。

プロバイダー セマンティクスはきれいに正規化されません。 単一のステータス列挙型は製品フローに役立ちますが、サポート チームには生のプロバイダー コード、ヘッダー、リクエスト ID、アダプター レベルの証拠が必要です。正規化されたレコードと生のレコードの両方を保持します。

BYOK により請求責任が変更されます。 BYOK により顧客はプロバイダー契約を制御できるようになりますが、プロバイダーの請求書を照合するゲートウェイの機能が低下する可能性があります。ゲートウェイは、請求がプロバイダーによって調整されるか、ゲートウェイによって従量制で行われるか、部分的に行われるか、または顧客によって宣言されるかどうかを公開する必要があります。

厳格なオンボーディングにより、一部の営業主導のセットアップが遅くなります。 限定的なサンドボックス モードは役に立ちますが、明確にラベル付けし、上限を設け、自動プロダクション プロモーションからブロックする必要があります。本番ルーティングには、検証済みの機能とポリシー マッピングが必要です。

実装チェックリスト

• 明示的なライフサイクル状態と不変の認証情報バージョンを持つ BYOK 認証情報オブジェクトを作成します。
• 検証前にプロバイダー固有のバインディング フィールドを収集します。
• シークレットは Credential Vault にのみ保存します。生のキーではなく、フィンガープリントとボールト参照をログに記録します。
• プロバイダーを呼び出す前に静的チェックを実行します。
• 許可されている場合は読み取りプローブを実行し、プロバイダーの生の証拠を保存します。
• 顧客の同意とプローブ予算を使用して、要求されたモデル プロファイルごとに最小限の推論プローブを 1 つ実行します。
• 許可されていないモデル、ツール、エンドポイント、リージョンに対してゲートウェイ ポリシーのネガティブ テストを実行します。
• ブール値ではなく、信頼レベルを使用して能力マトリックスを保持します。
• 選択したシークレットを直接経由するのではなく、テナント ポリシーとモデル プロファイルの要件を経由してルーティングします。
• 顧客向けの障害メッセージを具体的な修復手順とともに公開します。
• ヘルスチェックをスケジュールし、実行時エラーから再チェックをトリガーします。
• ローテーションを並列検証として実装し、その後にアトミック ルーティング スイッチを実行します。

結論

最も安全な BYOK オンボーディング フローは、フォームではなく検証者です。お客様が指定したプロバイダー キーは検疫に入り、そのバインディング、権限、モデル アクセス、クォータ シグナル、エンドポイントの動作、レポート制限を証明してから、実際にサポートされている機能のみを利用できるようにする必要があります。

実際的な推奨事項は、検証を機能マトリックスとして保存し、テナント ポリシーを介してルーティングし、本番トラフィックの開始後に再チェックを続けることです。予測は単純です。プロバイダーのキー タイプ、ワークスペース コントロール、リージョン クォータ、およびモデル固有のアクセス許可がより詳細になり続けるため、BYOK を 1 回限りのシークレット アップロードとして扱うゲートウェイでは、回避可能な本番環境のエラーが増加するでしょう。認証情報の検証をコントロール プレーンの一部とするゲートウェイは、最初は顧客のオンボーディングに時間がかかりますが、トラフィックが開始された後の驚きは少なくなります。

関連資料

• ランタイム、管理者、請求、BYOK アクセスを分離するための認証情報ボールト パターン