顧客スコープの AI API キー: プロバイダー キーのスプロールを発生させずにテナント、予算、悪用を分離
SaaS 製品、代理店、再販業者のプラットフォームには、上流のプロバイダーの資格情報を公開せずに顧客レベルの AI アクセスが必要です。ゲートウェイが発行した仮想キーを、テナント属性、モデル アクセス、予算、レート制限、失効、ローテーション、および使用状況台帳のポリシー ハンドルとして使用します。
製品で多くの顧客が AI モデルを呼び出すことができる場合、間違ったプリミティブが上流のプロバイダ キーであることがよくあります。プロバイダー キーは通常、アカウント、プロジェクト、ワークスペース、またはサービス アカウントを表します。製品には、より狭いものが必要です。つまり、1 つのテナント、顧客、アプリケーション、環境、モデル ポリシー、予算、監査ルールを識別する顧客向けのキーです。
これが顧客スコープの AI API キーの目的です。ゲートウェイはキーを発行し、リクエストを認証し、ポリシーを適用し、使用量を測定してから、非表示の資格情報を使用して上流のプロバイダーを呼び出します。下流の顧客がプロバイダー キーを受け取ることはありません。彼らはあなたのプラットフォームと安定した契約を結びます。
読者の問題: 顧客ごとに 1 つのプロバイダー プロジェクトがないと顧客が孤立する
SaaS ビルダー、代理店、再販プラットフォームは通常、AI アクセスをダウンストリームに公開する前に、実際的な質問に答える必要があります:
- この使用量を生成したのはどの顧客ですか?
- 呼び出しを行ったアプリケーション、環境、または統合はどれですか?
- どのモデルとモダリティが許可されますか?
- この顧客は今月いくら使えますか?
- キーが漏れたらどうなりますか?
- 他のユーザーに影響を与えずに、この顧客を停止することはできますか?
- 後でプロバイダーのレポートに基づいて使用状況を調整できますか?
プロバイダー側のプロジェクトとワークスペースは役立ちますが、すべての下流顧客にとって必ずしも適切なユニットであるとは限りません。顧客ごとに 1 つの上流境界を作成すると、ハード分離とレポート機能が向上しますが、プロビジョニングのオーバーヘッド、クォータの断片化、認証情報の無秩序な増加など、調整作業も発生します。
ゲートウェイ発行のキーは、アップストリームの認証情報がプールされている場合でも、製品に顧客レベルの制御ポイントを提供します。また、顧客が契約上の分離、居住地の境界、またはプロバイダー アカウントの直接所有権を必要とする場合に、テナントにバインドされたプロバイダー資格情報や個人キーの持ち込みなど、より強力なモードもサポートします。
事実、推奨事項、予測
事実
- OpenAI プロジェクトは、メンバー、サービス アカウント、API キー、使用制限、予算、および範囲指定されたプロジェクト リソースをサポートします。そのため、プロジェクトは上流の境界として役立ちますが、すべてのエンド顧客にとって自動的に適切なプリミティブになるわけではありません。
- OpenAI 使用状況レポートでは、プロジェクト、ユーザー、API キー、モデル、バッチ、サービス層などのディメンションごとに使用状況をグループ化できます。 SaaS チャージバックには、製品所有の顧客 ID に結合されたプロバイダー レコードが依然として必要です。
- Anthropic ワークスペースは、API 個のリソースをユースケース、チーム、部門、プロジェクト、または製品ごとに分離します。 API キーは、キーが作成されたワークスペースに関連付けられており、ワークスペース間で移動することはできません。
- Anthropic 使用状況とコストのレポートは、API キー、ワークスペース、モデル、サービス レベル、コンテキスト ウィンドウ、データの保存場所、速度関連のオプションによるグループ化をサポートしており、コストは日次 USD バケットで返されます。
- Google Gemini API キーのガイダンスではキーを制限することが推奨されており、Gemini API キーはデフォルトで生成言語 API に制限されています。導入形態に応じて、IP アドレスなどのアプリケーション制限を利用できる場合があります。
- OWASP ガイダンスでは、API 個のキーを保護されたエンドポイントに必要な制御として扱い、クライアントが使用契約に違反した場合にはキーを取り消す必要があると述べています。
- OWASP シークレットのガイダンスでは、最小限の権限、シークレットが不要になった場合や侵害された場合の取り消し、実装エラーを減らすための自動ローテーションが強調されています。
推奨事項
- 認証トークンだけでなく、ゲートウェイが発行した顧客キーをポリシー ハンドルとして使用します。
- 上流のプロバイダーの認証情報を下流の顧客から隠しておいてください。
- プロバイダのダッシュボードに頼る前に、リクエスト時にゲートウェイ使用状況台帳を作成します。
- 高リスク、大量の顧客、規制されている顧客、居住地に依存する顧客、または契約上別の顧客に対して、プロバイダ プロジェクトまたはワークスペースを選択的に使用します。
- 即時の破損イベントとしてではなく、重複ワークフローとしてキーのローテーションを構築します。
予測
- より多くのプロバイダーが、より充実した使用状況のグループ化と予算管理を公開することになりますが、SaaS の請求や再販業者のレポートには、製品所有の顧客属性が依然として必要です。
- 再販業者や代理店のプラットフォームは、ゲートウェイ キーをプラン、クレジット残高、範囲、サポート ワークフローに関連付けられた商用オブジェクトとして扱うことが増えています。
- 厳格なコンプライアンスや調達のニーズがある顧客は、BYOK またはプロバイダー アカウントの所有権を要求しますが、ほとんどの一般顧客はマネージド ゲートウェイ契約を好みます。
ゲートウェイ キー オブジェクト
顧客スコープのキーは構造化ポリシー オブジェクトに解決される必要があります。少なくとも、ハッシュと名前以上のものとしてキーをモデル化します。
{
"key_id": "key_01J9...",
"tenant_id": "tenant_acme",
"customer_id": "cust_4812",
"application_id": "app_support_bot",
"environment": "production",
"owner": {
"type": "service_account",
"id": "svc_support_ai"
},
"model_profile_id": "profile_support_standard",
"allowed_modalities": ["text", "image_input"],
"tool_policy_id": "tools_readonly_kb",
"monthly_budget": {
"currency": "USD",
"amount": "500.00"
},
"rate_limits": {
"requests_per_minute": 120,
"input_tokens_per_minute": 250000,
"output_tokens_per_minute": 80000
},
"retention_policy": "metadata_only",
"status": "active",
"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 billing に接続します。
4.シークレットを正しく生成して保存する
平文のシークレットを 1 回表示します。強力なハッシュと、サポート検索用の短いプレフィックスまたはフィンガープリントのみを保存します。プレフィックスは、サポート チームがシークレットを確認せずに「8F2A で終わるキー」を識別するのに役立ちます。
一般的なストレージ パターンは次のとおりです:
key_id: 安定したデータベース識別子。secret_hash: 適切なパスワードまたはトークン ハッシュ戦略を使用した完全なシークレットのハッシュ。secret_prefix: 短い非機密表示プレフィックス。fingerprint: 監査ルックアップの決定的な識別子。created_by: キーを作成したユーザーまたはパートナー API クライアント。status: アクティブ、ドレイン、取り消し、隔離、期限切れ。
上流プロバイダー キーを顧客キー オブジェクトに保存しないでください。プロバイダーの資格情報は、独自のアクセス ルールを持つ別の資格情報ボールトに属します。
リクエスト時の強制
ゲートウェイは、各モデル呼び出しをポリシー決定として処理し、その後にプロバイダーをディスパッチする必要があります。実際のリクエスト パスは次のようになります:
- 提示されたゲートウェイ キーを解析します。
- キーのハッシュとステータスを調べます。
- テナント、顧客、アプリケーション、環境、所有者、およびモデルのプロファイルを解決します。
- テナントと顧客がアクティブかどうかを確認します。
- リクエストされたモデルのエイリアス、モダリティ、ツール、保持モード、リージョン、サービス層を検証します。
- リクエストのコストと予算を見積もります。
- レート制限と不正使用のしきい値を確認します。
- アップストリーム認証情報モードを選択します: プール、テナント バインド、または BYOK。
- プロバイダにディスパッチします。
- 使用状況、コスト、プロバイダー参照、エラー、安全信号をキャプチャします。
- 予算の予約を確定し、最終的な台帳イベントを書き込みます。
このシーケンスにより、ゲートウェイは顧客の契約に対して責任を負います。プロバイダーのダッシュボードは、唯一の真実の情報源ではなく、調整の入力情報になります。
後で実際に役立つ使用状況元帳フィールド
ゲートウェイ台帳は、デフォルトで生のプロンプト ストレージを必要とせずに、サポート、請求、不正使用、ルーティングの質問に答えるのに十分な詳細を保存する必要があります。
便利なフィールドは次のとおりです:
request_idとtrace_id.tenant_id、customer_id、application_id、key_id.- エンドユーザー識別子。必要に応じて仮名を使用することが望ましい。
- 顧客が要求したモデルのエイリアス。
- 上流のプロバイダーとモデルを解決しました。
- 該当する場合、入力、出力、推論、キャッシュされた音声、画像、ビデオ、およびツールの使用法。
- 見積コスト、予約金額、決済コスト、通貨、および価格カタログのバージョン。
- プロバイダー リクエスト ID、使用状況レポート参照、プロジェクト、ワークスペース、または API キー グループ化ディメンション (利用可能な場合)。
- 保持ポリシーが適用されました。
- 安全性、悪用、またはポリシー決定コード。
- エラー カテゴリと再試行メタデータ。
この構造は、チャージバック、カスタマー サポート、インシデント対応、および「このキーは何をしたのか?」に答えることができる API キー管理 ワークフローをサポートします。無関係なテナントを公開する必要はありません。
認証情報モード: プール、テナント バインド、BYOK
プールされたプロバイダー認証情報
デフォルト モードでは、多くの顧客キーは、より小規模なプロバイダー認証情報のセットを介してルーティングされます。これは操作的に簡単で、プロバイダー側のスプロールを軽減します。これは、ゲートウェイに強力なテナント属性、予算の強制、レート制限、不正行為の隔離、およびキャッシュ境界制御がある場合に機能します。
トレードオフとして、プロバイダー側のレポートにはゲートウェイ資格情報またはプロバイダー プロジェクトしか表示されない可能性があります。顧客レベルの請求と分析を生成するには、プロバイダーのレコードをゲートウェイの台帳レコードに結合し直す必要があります。
テナントにバインドされたプロバイダーの認証情報
大規模またはリスクの高いテナントの場合は、テナントを専用のプロバイダー プロジェクト、ワークスペース、サービス アカウント、またはキーにバインドします。これにより、アップストリームの分離が強化され、プロバイダー側のレポートが簡素化される可能性があります。プロバイダーがその境界での制限をサポートしている場合は、ハード クォータ バックストップを提供することもできます。
コストは運用の複雑さです。プロビジョニング、ローテーション、プロバイダーの制限、インシデント対応、調整が、より多くの上流オブジェクト間で行われるようになりました。
自分の鍵を持参する
BYOK は、顧客がプロバイダー アカウントを所有する必要がある場合、独自のプロバイダー契約を交渉する必要がある場合、またはプロバイダーの請求を個別に維持する必要がある場合に役立ちます。ゲートウェイは、可能な場合にはモデル プロファイル、ルーティング ポリシー、分析、およびアプリケーション レベルの制御を引き続き適用します。
トレードオフはサポートの複雑さです。各顧客のプロバイダー アカウントには、異なるモデル アクセス、クォータ、価格設定、保持設定、およびインシデント ステータスが設定されている場合があります。ゲートウェイはこれらの違いを検出し、明確に説明する必要があります。
失効と隔離
取り消しでは、関連のない上流プロバイダーの資格情報をローテーションすることなく、顧客キーに対する新しいリクエストを即座にブロックする必要があります。これは、仮想キーの主な利点の 1 つです。
さまざまな操作アクションに対して個別の状態を使用します:
active: リクエストは許可されます。draining: ローテーション期間中は古いキーが受け入れられますが、警告と監査イベントが生成されます。revoked: 新しいリクエストは永久に拒否されます。quarantined: 不正行為、支払い、ポリシー、またはインシデント対応のため、新しいリクエストはブロックされています。expired: キーの有効期間を超えたため、交換する必要があります。
インシデントが解決された場合、隔離は元に戻せる必要があります。古いシークレットを復元すると混乱とリスクが増大するため、通常、失効は元に戻せません。
キーが使用ポリシーに違反した場合、その理由、行為者、時間、および適用範囲を記録します。決定が自動化された場合は、ルールのバージョンとそれをトリガーしたシグナルを保存します。これにより、顧客との会話が事実に保たれます。
生産を中断することなく回転
キーのローテーションでは、2 つのキーの重複ワークフローを使用する必要があります:
- オペレーターが意図的に変更しない限り、同じ顧客、アプリケーション、モデル プロファイル、および制限を使用して置換キーを作成します。
- 新しいシークレットを 1 回表示します。
- 古いキーを
drainingとしてマークします。 - 顧客のプランとリスクに応じて、7 日、14 日、30 日などの制限された期間、両方のキーを受け入れます。
- ドレイン キーの使用状況に関する警告を発します。
- 古いキーが期限近くになっても使用されている場合は、所有者またはパートナー API クライアントに通知します。
- ウィンドウの最後に古いキーを取り消します。
- 同じ顧客とアプリケーションの下で両方のキー ID の帰属を維持します。
これにより、セキュリティの向上が本番の停止になるという一般的な障害モードが回避されます。ローテーションはまだコントロールですが、証拠と期限を伴う運用ワークフローになります。
パートナー 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 を使用します。通常のパスの場合は、ゲートウェイ台帳とポリシー エンジンで顧客の分離を実施し、その後プロバイダー レコードを調整します。