顧客スコープの AI API キー: プロバイダー キーのスプロールを発生させずにテナント、予算、悪用を分離
SaaS 製品、代理店、再販業者のプラットフォームには、上流のプロバイダーの資格情報を公開せずに顧客レベルの AI アクセスが必要です。ゲートウェイが発行した仮想キーを、テナント属性、モデル アクセス、予算、レート制限、失効、ローテーション、および使用状況台帳のポリシー ハンドルとして使用します。
製品で多くの顧客が AI モデルを呼び出すことができる場合、間違ったプリミティブが上流のプロバイダー キーであることがよくあります。プロバイダー キーは通常、アカウント、プロジェクト、ワークスペース、またはサービス アカウントを表します。あなたの製品には、より狭いものが必要です。つまり、1 つのテナント、顧客、アプリケーション、環境、モデル ポリシー、予算、監査ルールを識別する顧客向けのキーです。
これが、顧客スコープの AI API キーの目的です。ゲートウェイはキーを発行し、リクエストを認証し、ポリシーを適用し、使用量を測定してから、非表示の資格情報を使用して上流のプロバイダーを呼び出します。下流の顧客がプロバイダー キーを受け取ることはありません。彼らはあなたのプラットフォームと安定した契約を結びます。
読者の問題: 顧客ごとに 1 つのプロバイダー プロジェクトがないと顧客が孤立する
SaaS ビルダー、代理店、再販プラットフォームは通常、AI アクセスを下流に公開する前に、実際的な質問に答える必要があります。
- この使用量を生成したのはどの顧客ですか?
- 呼び出しを行ったアプリケーション、環境、または統合はどれですか?
- どのモデルとモダリティが許可されますか?
- この顧客は今月いくら使えますか?
- キーが漏洩した場合はどうなりますか?
- 他のユーザーに影響を与えずに、この顧客を停止することはできますか?
- 使用状況を後でプロバイダーのレポートと照合できますか?
プロバイダー側のプロジェクトとワークスペースは役立ちますが、すべての下流顧客にとって必ずしも適切なユニットであるとは限りません。顧客ごとに 1 つの上流境界を作成すると、ハード分離とレポート機能が向上しますが、プロビジョニングのオーバーヘッド、クォータの断片化、認証情報の無秩序な増加など、調整作業も発生します。
ゲートウェイ発行のキーは、上流の認証情報がプールされている場合でも、製品に顧客レベルの制御ポイントを提供します。また、顧客が契約上の分離、居住境界、またはプロバイダ アカウントの直接所有権を必要とする場合、テナントにバインドされたプロバイダ認証情報や個人キーの持ち込みなど、より強力なモードもサポートされます。
事実、推奨事項、予測
事実
- OpenAI プロジェクトは、メンバー、サービス アカウント、API キー、使用制限、予算、限定されたプロジェクト リソースをサポートします。そのため、プロジェクトは上流の境界として役立ちますが、すべてのエンド顧客にとって自動的に適切なプリミティブになるわけではありません。
- OpenAI 使用状況レポートでは、プロジェクト、ユーザー、API キー、モデル、バッチ、サービス層などのディメンションごとに使用状況をグループ化できます。 SaaS チャージバックでは、プロダクト所有の顧客 ID に結合されたプロバイダー レコードが引き続き必要です。
- 人間的なワークスペースは、API リソースをユースケース、チーム、部門、プロジェクト、製品ごとに分離します。 API キーは作成されたワークスペースに関連付けられており、ワークスペース間で移動することはできません。
- 人為的な使用量とコストのレポートは、API キー、ワークスペース、モデル、サービス レベル、コンテキスト ウィンドウ、データの所在地、速度関連のオプションによるグループ化をサポートしており、コストは日次の米ドル バケットで返されます。
- Google Gemini API キーのガイダンスではキーを制限することが推奨されており、Gemini API キーはデフォルトで生成言語 API に制限されています。導入形態に応じて、IP アドレスなどのアプリケーション制限を利用できる場合があります。
- OWASP ガイダンスでは、API キーを保護されたエンドポイントに必要な制御として扱い、クライアントが使用契約に違反した場合にはキーを取り消す必要があると述べています。
- OWASP シークレットのガイダンスでは、最小限の権限、シークレットが不要になった場合や漏洩した場合の取り消し、実装エラーを減らすための自動ローテーションが強調されています。
推奨事項
- ゲートウェイが発行したカスタマー キーを認証トークンだけでなくポリシー ハンドルとして使用する
- 上流のプロバイダの認証情報を下流の顧客から隠しておく
- プロバイダのダッシュボードに頼る前に、リクエスト時にゲートウェイの使用状況台帳を作成します。
- リスクが高く、取引量が多く、規制があり、居住地が重要な顧客、または契約上別居している顧客に対して、プロバイダ プロジェクトやワークスペースを選択的に使用する
- 即時の破損イベントとしてではなく、オーバーラップ ワークフローとしてキーのローテーションを構築します。
予測
- より多くのプロバイダが、より充実した使用状況のグループ化と予算管理を公開することになりますが、SaaS の請求や販売代理店のレポートには、製品所有の顧客の属性が依然として必要となります。
- 再販業者や代理店のプラットフォームは、ゲートウェイ キーをプラン、クレジット残高、範囲、サポート ワークフローに関連付けられた商用オブジェクトとして扱うことが増えています。
- 厳格なコンプライアンスや調達のニーズがある顧客は、BYOK またはプロバイダ アカウントの所有権を要求しますが、ほとんどの一般的な顧客はマネージド ゲートウェイ契約を好むでしょう。
ゲートウェイ キー オブジェクト
顧客スコープのキーは、構造化されたポリシー オブジェクトに解決される必要があります。少なくとも、ハッシュと名前以上のものとしてキーをモデル化します。
{
"key_id": "key_01J9...",
"テナントID": "テナント_acme",
"customer_id": "cust_4812","application_id": "app_support_bot",
"環境": "生産"、
「所有者」: {
"タイプ": "サービスアカウント",
"id": "svc_support_ai"
}、
"model_profile_id": "profile_support_standard",
"allowed_modalities": ["テキスト", "画像入力"],
"tool_policy_id": "tools_readonly_kb",
"月間予算": {
"通貨": "USD",
「金額」：「500.00」
}、
"rate_limits": {
「分あたりのリクエスト数」: 120、
「1 分あたりの入力トークン」: 250000、
「分あたりの出力トークン」: 80000
}、
"retention_policy": "metadata_only",
"ステータス": "アクティブ",
"created_at": "2026-09-05T10:00:00Z",
"last_used_at": null
}正確なフィールドは異なりますが、原則としてそうではありません。すべての受信リクエストは、ディスパッチ前にキーをテナント ポリシーに解決します。認証は「誰が電話をかけてきたのか?」に答えます。ポリシー解決は、「この呼び出し元は何をすることができますか、いくら費やすことができますか、リクエストはどこにルーティングされますか、そして何をログに記録する必要がありますか?」
これは、セマンティック製品戦略が重要な点でもあります。 代理店向け AI API を販売するプラットフォームには、顧客およびキャンペーンのディメンションが必要な場合があります。開発者ツールには、ワークスペースとリポジトリのディメンションが必要な場合があります。再販業者は、請求システムと一致する外部顧客 ID を必要とする場合があります。
キー作成ワークフロー
キーの作成は、自動化できるほど決定的であり、セキュリティ レビューできるほど厳密である必要があります。
1.最初に顧客レコードを作成します
孤立したキーを作成しないでください。キーは、存在する前にテナントと顧客レコードに属している必要があります。再販業者プラットフォームの場合、顧客レコードには、再販業者の CRM または請求システムからの外部 ID、プランのメタデータ、必要に応じて税金または請求書のグループ化、およびすべての子キーを一時停止できるステータス フィールドを含める必要があります。
2.モデルプロファイルを添付する
モデル プロファイルは、顧客向けモデル名をプロバイダーのモデルと機能にマッピングします。たとえば、support-standard を使用すると、バランスの取れたテキスト モデル、画像入力が可能になり、コードは実行されなくなります。 research-premium では、ロングコンテキスト モデル、Web 検索、およびリクエストごとの上限の引き上げが可能になる可能性があります。
ダウンストリーム アプリケーションにプロバイダー モデル ID のハードコーディングを強制しないでください。ゲートウェイ プロファイルを使用して、可用性、フォールバック、価格設定、非推奨を管理します。
3.支出制限とレート制限を設定する
予算とレート制限を併用します。毎月の予算を設定することで、長期にわたる請求書の損傷を防ぎます。レート制限により、突然の乱用、再試行の嵐、または偶発的なループによって数分で予算全体が消費されるのを防ぎます。
便利なコントロールには次のものがあります。
- 顧客の月次予算
- 異常検出のための毎日のソフトキャップ
- キーごとのリクエスト率
- 入力および出力トークン レート。
- リクエストごとの最大推定コスト
- ホスト型検索、ファイル処理、コード実行に対するツール固有の制限
予算執行では、発送前に見積コストを留保し、完了後に実際のコストを決済し、未使用の留保額を解放する必要があります。これにより、請求を遅延レポート タスクとして扱うのではなく、キー ポリシーを AI API の請求に関連付けます。
4.シークレットを正しく生成して保存する
プレーンテキストのシークレットを 1 回表示します。強力なハッシュと、サポート検索用の短いプレフィックスまたはフィンガープリントのみを保存します。プレフィックスは、サポート チームが秘密を確認することなく「8F2A で終わるキー」を識別するのに役立ちます。
一般的な保存パターンは次のとおりです:
key_id: 安定したデータベース識別子。secret_hash: 適切なパスワードまたはトークン ハッシュ戦略を使用した完全なシークレットのハッシュ。secret_prefix: 短い非機密表示プレフィックス。フィンガープリント: 監査検索のための決定的な識別子。created_by: キーを作成したユーザーまたはパートナー API クライアント。ステータス: アクティブ、ドレイン、取り消し、隔離、期限切れ。
上流のプロバイダー キーをカスタマー キー オブジェクトに保存しないでください。プロバイダーの認証情報は、独自のアクセス ルールを持つ別の認証情報ボールトに属します。
リクエスト時の強制
ゲートウェイは、各モデル呼び出しをポリシーの決定として処理し、その後にプロバイダーのディスパッチを行う必要があります。実際のリクエスト パスは次のようになります。
<オル>このシーケンスにより、ゲートウェイは顧客の契約に対して責任を負い続けます。プロバイダーのダッシュボードは、唯一の真実の情報源ではなく、調整の入力情報となります。
後で実際に役立つ使用状況元帳フィールド
ゲートウェイ台帳は、デフォルトで未加工のプロンプト ストレージを必要とせずに、サポート、請求、不正使用、ルーティングの質問に答えるのに十分な詳細を保存する必要があります。
便利なフィールドは次のとおりです:
request_idとtrace_id。tenant_id、customer_id、application_id、およびkey_id。- エンドユーザー識別子。必要に応じて仮名を使用することが望ましい。
- 顧客がリクエストしたモデルのエイリアス。
- 上流のプロバイダーとモデルを解決しました。
- 該当する場合、入力、出力、推論、キャッシュ、音声、画像、動画、ツールの使用法
- 見積コスト、予約金額、決済コスト、通貨、価格カタログのバージョン
- プロバイダー リクエスト ID、使用状況レポート参照、プロジェクト、ワークスペース、または API キー グループ化ディメンション（利用可能な場合）
- 保持ポリシーが適用されました。
- 安全性、悪用、またはポリシー決定コード
- エラー カテゴリと再試行メタデータ。
この構造は、チャージバック、カスタマー サポート、インシデント対応、そして「このキーは何をしたのか?」に答えることができるAPI キー管理ワークフローをサポートしています。無関係なテナントを公開することなく。
認証情報モード: プール、テナント バインド、BYOK
プールされたプロバイダ認証情報
デフォルト モードでは、多くの顧客キーが、より小規模なプロバイダー認証情報のセットを介してルーティングされます。これは操作が簡単で、プロバイダー側のスプロールを軽減します。これは、ゲートウェイに強力なテナント属性、予算の適用、レート制限、不正行為の隔離、キャッシュ境界制御が設定されている場合に機能します。
トレードオフとして、プロバイダー側のレポートにはゲートウェイ認証情報またはプロバイダー プロジェクトしか表示されない可能性があります。顧客レベルの請求と分析を生成するには、プロバイダーのレコードをゲートウェイの台帳レコードに結合し直す必要があります。
テナントにバインドされたプロバイダーの認証情報
大規模またはリスクの高いテナントの場合は、テナントを専用のプロバイダー プロジェクト、ワークスペース、サービス アカウント、またはキーにバインドします。これにより、アップストリームの分離が強化され、プロバイダー側のレポートが簡素化される可能性があります。プロバイダーがその境界での制限をサポートしている場合は、ハード クォータ バックストップを提供することもできます。
コストは運用の複雑さです。プロビジョニング、ローテーション、プロバイダ制限、インシデント対応、調整が、より多くの上流オブジェクト間で行われるようになりました。
自分のキーを持参してください
BYOK は、顧客がプロバイダー アカウントを所有する必要がある場合、独自のプロバイダー契約を交渉する必要がある場合、またはプロバイダーの請求を個別に維持する必要がある場合に役立ちます。ゲートウェイは、可能な場合にはモデル プロファイル、ルーティング ポリシー、分析、アプリケーション レベルの制御を引き続き適用します。
トレードオフはサポートの複雑さです。各顧客のプロバイダー アカウントには、異なるモデル アクセス、クォータ、価格設定、保持設定、およびインシデント ステータスが設定されている場合があります。ゲートウェイはこれらの違いを検出し、明確に説明する必要があります。
失効と隔離
取り消しでは、関連のない上流プロバイダーの認証情報をローテーションすることなく、顧客キーに対する新しいリクエストを即座にブロックする必要があります。これは、仮想キーの主な利点の 1 つです。
さまざまな操作アクションに対して個別の状態を使用します。
active: リクエストは許可されます。draining: ローテーション期間中は古いキーが受け入れられますが、警告と監査イベントが生成されます。revoked: 新しいリクエストは永久に拒否されます。quarantinated: 不正行為、支払い、ポリシー、またはインシデント対応のため、新しいリクエストはブロックされます。期限切れ: キーの有効期間を超えたため、交換する必要があります。
インシデントが解決された場合、隔離は元に戻せる必要があります。古いシークレットを復元すると混乱とリスクが増大するため、通常、取り消しを元に戻すことはできません。
キーが使用ポリシーに違反した場合は、その理由、行為者、時間、および適用範囲を記録します。決定が自動化された場合は、ルールのバージョンとそれをトリガーしたシグナルを保存します。これにより、顧客との会話が事実に保たれます。
生産を中断することなく回転
キーのローテーションでは、2 つのキーのオーバーラップ ワークフローを使用する必要があります。
<オル>draining としてマークします。これにより、セキュリティの向上が本番の停止になるという一般的な障害モードが回避されます。ローテーションは依然としてコントロールですが、証拠と期限を伴う運用ワークフローになります。
パートナー API サーフェス
ダウンストリーム プラットフォームが顧客をプログラムで管理する場合は、パートナー API を通じて主要な操作を公開します。プロビジョニングは請求、オンボーディング、または CRM ワークフロー内で行われることが多いため、API は冪等キーと監査イベントをサポートする必要があります。
最小エンドポイント:
POST /customers: 顧客を作成または更新/挿入します。POST /customers/{customer_id}/keys: キーを作成します。GET /customers/{customer_id}/keys: キーとステータスをリストします。PATCH /keys/{key_id}: スコープ、所有者、制限、モデル プロファイル、またはステータスを更新します。POST /keys/{key_id}/rotate: 代替キーを作成し、古いキーをドレインとしてマークします。POST /keys/{key_id}/revoke: すぐに取り消します。GET /customers/{customer_id}/usage: 時間範囲、キー、アプリ、モデル、またはエンドユーザー ディメンション別に使用量とコストを返します。
すべての変更リクエストはべき等キーを受け入れる必要があります。すべての変更では、アクター、ターゲット、前後フィールド、ソース IP またはクライアント ID、および可能な場合は理由を含む監査イベントを書き込む必要があります。
プロバイダー プロジェクトまたはワークスペースを使用する場合
ゲートウェイ キーとプロバイダー境界を相互に排他的なものとして扱わないでください。彼らはさまざまな問題を解決します。
通常の顧客レベルの制御にはゲートウェイ キーを使用します。
- 顧客ごとの帰属。
- アプリケーションごとのキー。
- 予算とレート制限。
- 迅速な一時停止。
- ローテーション ワークフロー。
- 使用状況分析と販売代理店レポート
顧客がより強力な分離を必要とする場合は、プロバイダー プロジェクト、ワークスペース、または専用プロバイダーの認証情報を追加します。
- 専用割り当てに値する月間ボリュームが多い
- 明示的な常駐または保持要件を伴う規制されたワークロード
- 契約上の請求書の分離
- プロバイダ側の厳しい予算または割り当てのバックストップ
- 専用の乱用監視または安全性レビューの境界
- BYOK による顧客所有のプロバイダ アカウント
実際のデフォルトは、選択的なアップストリームのハード境界によるゲートウェイ強制分離です。これにより、共通のパスがシンプルに保たれ、さらに分離が必要な顧客のためのエスカレーション パスも確保されます。
実装チェックリスト
- テナント、顧客、アプリケーション、環境、所有者、モデル プロファイル、制限、保持ポリシー、ステータスを含む顧客キー スキーマを定義する
- 保存時にシークレットをハッシュし、平文を 1 回だけ表示します。
- ゲートウェイ キーをアップストリーム プロバイダーの認証情報ストレージから分離する
- すべてのリクエストを送信前にポリシーに解決します。
- プロバイダに電話する前に予算を予約し、最終的な使用量がわかった後に決済する
- 顧客、キー、モデル エイリアス、アップストリーム モデル、トークン カテゴリ、ツールの使用状況、見積コスト、決済コスト、プロバイダー参照の使用状況を記録する
- アクティブ、ドレイン、取り消し、隔離、期限切れの各状態を実装する
- 2 つのキー回転のオーバーラップをサポートします。
- 冪等キーを使用してパートナー API オペレーションを公開する
- プロバイダのプロジェクトやワークスペースは、運用コストが正当な場合にのみ使用してください。
実用的な結論
AI アクセスのための顧客の分離は通常、プロバイダー キーではなくゲートウェイ キーから開始する必要があります。ゲートウェイ キーは顧客向けの契約であり、テナント、顧客、アプリケーション、モデル プロファイル、予算、レート制限、保持ルール、監査ポリシーの名前が付けられます。プロバイダー キーは、そのコントラクトの背後にある実装の詳細です。
このアーキテクチャにより、SaaS ビルダーと再販業者のプラットフォームは、デフォルトで顧客ごとに 1 つのアップストリーム プロバイダー プロジェクトを作成することなく、迅速な取り消し、正確な属性、顧客ごとの予算、制御されたローテーション、有用な使用状況分析を実現できます。リスク、ボリューム、常駐、または契約で必要な場合は、アップストリームのプロジェクト、ワークスペース、テナントにバインドされた認証情報、または BYOK を使用します。通常のパスの場合、ゲートウェイ台帳とポリシー エンジンで顧客の分離を強制し、その後プロバイダーのレコードを調整します。