顧客 API キー プロビジョニングは、顧客、テナント、アプリ、ボット、チーム、または再販業者アカウントのモデル API 認証情報を作成、割り当て、制限、ローテーション、一時停止、監査する運用パターンです。企業がすべての顧客に 1 つのモデル キーを共有してほしくない場合や、上流のプロバイダーの資格情報や特権管理トークンを公開したくない場合には、これが重要になります。
通常、LLM 製品が単一の内部統合を超えて移行すると、必要性が現れます。再販業者パネルは、下流の顧客にキーを発行する必要がある場合があります。 SaaS プラットフォームでは、各ワークスペースに独自のモデル キーが必要な場合があります。ボットプロバイダーは、ボット所有者ごとに個別の資格情報を必要とする場合があります。社内の AI プラットフォーム チームは、手動のダッシュボード作業を待たずに、部門、テスト環境、または運用サービスにキーをプロビジョニングする必要がある場合があります。
中心的な問題は、LLM API キーの自動作成だけではありません。耐久性のあるプロビジョニング システムは、誰がキーを所有するか、どのグループまたはプランが適用されるか、どのような使用制限が存在するか、費用がどのように帰属するか、キーがローテーションされたときに何が起こるか、サポートによるリクエストの調査方法、タイムアウト後の再試行の動作、監査証跡のセキュリティ チームや財務チームが信頼できるものは何かなど、より難しい質問に答える必要があります。
顧客 API のキー プロビジョニングの意味
LLM プラットフォームでは、顧客向けの API キーは、推論リクエストの認証に使用される資格情報です。通常、アカウントの管理に使用される資格情報よりも狭い値にする必要があります。顧客キーはモデルを呼び出します。パートナーまたは管理者の認証情報は、これらの顧客キーを作成および管理します。
これにより、2 層の認証情報モデルが作成されます:
- パートナー レベルまたはアカウント レベルの認証情報: 信頼できるバックエンドがモデル API キーの作成、更新、回転、凍結、削除、リスト、検査に使用する特権サーバー側の認証情報。
- 顧客向けモデル キー: 顧客、テナント、アプリ、ボット、ワークスペース、またはサービスが推論トラフィックを送信するために使用するより狭い資格情報。
- グループまたはテナントの割り当て: キーを顧客、プラン、環境、製品、または再販業者のサブアカウントにマッピングする所有権およびポリシー層。
分離は重要です。顧客モデル キーでは、追加のキーの作成、請求構成の変更、無関係な顧客の使用状況の読み取り、または他のテナントの管理を行うことはできません。プロビジョニング資格情報は、ブラウザー、モバイル アプリ、顧客スクリプト、パブリック リポジトリ、または顧客が制御する自動化に決して表示されるべきではありません。これは、バックエンド サービス、保護されたランタイム、またはシークレット マネージャーに属します。
B2B LLM は、このパターンの実装の 1 つです。そのパートナー API は、モデル API のキー、グループ、制限、使用状況、リクエスト履歴、残高、監査イベント、および非同期結果を管理する信頼できるサーバー間の統合を目的としています。一般的な設計原則はより広範囲に適用されます。つまり、プロビジョニングはコントロール プレーンの機能であり、推論はデータ プレーンの機能です。
パートナー側のキーのプロビジョニングが必要な場合
ダッシュボード キーの手動作成は、初期の実験中に機能する可能性があります。キーの発行がオンボーディング、請求、資格付与、サポート、または顧客のセルフサービスの一部になると、拡張が停止します。
通常、パートナー側のプロビジョニングは次の場合に必要になります。
- 顧客は、サポート スタッフが手動でキーをそれぞれ作成することなく、独自のキーを受け取る必要があります。
- 再販業者またはホワイトラベル製品は、独自の商用モデルに基づいて顧客に LLM API キーをプロビジョニングする必要があります。
- 各テナント、ワークスペース、ボット、アプリ、または環境には、個別の使用属性が必要です。
- 顧客ごとに、異なる支出制限、レート制限、許可されたモデル、またはステータス管理が必要です。
- サポート チームは、インシデント発生時に顧客キーを迅速に凍結、ローテーション、または検査する必要があります。
- 財務では、顧客、グループ、プラン、または販売代理店アカウントごとの使用状況とコストの記録が必要です。
- セキュリティ ポリシーには、失効、監査証跡、最小権限、および秘密の処理制御が必要です。
より広範な AI アクセス インフラストラクチャを構築しているチームの場合、キー プロビジョニングは通常、ルーティング、ポリシーの適用、分析、プロバイダーの抽象化と並行して行われます。これは AI API コントロール プレーン の一部であり、単なる便利なエンドポイントではありません。
最初に主要モデルを設計します
最も一般的なプロビジョニングの間違いは、エンドポイントが制御するエンティティを定義する前にエンドポイントを構築することです。 B2B LLM および類似のプラットフォームでは、アカウント所有者、パートナー システム、従業員オペレーター、再販業者、下流顧客、グループ、モデル キー、エンド ユーザーはすべて異なるプリンシパルである可能性があります。
実用的なモデルでは以下を定義する必要があります:
- アカウント: プラットフォーム残高とパートナー認証情報の商用または管理所有者。
- オペレーター: プロビジョニング アクションを開始した人間またはサービス。
- 顧客またはテナント: サービスを受ける下流のビジネス、ワークスペース、アプリ、ボット所有者、または部門。
- グループ: 制限、分析、サポート、プランの割り当てに使用されるポリシーとレポート コンテナ。
- モデル キー: API 呼び出しで使用される実際の推論資格情報。
- リクエスト アクター: アクティビティを後で追跡する必要がある可能性があるランタイム サービス、顧客アプリケーション、またはユーザー。
これらの区別により、曖昧さが回避されます。リセラーの従業員が顧客のワークスペースのキーを作成した場合、監査証跡により、オペレーター、リセラーのコンテキスト、顧客のターゲット、および結果として得られるキーのプレフィックスが特定される必要があります。キーが制限を超えた場合、サポートはその制限がキー、グループ、顧客プラン、またはアカウント残高に属しているかどうかを知る必要があります。
実用的なキー作成ワークフロー
強力なキー作成ワークフローは、トークンを返すだけではありません。これにより、運用上役立つ ID が作成されます。
1.安定した顧客コンテキストを収集
顧客名だけでなく、永続的な識別子を使用します。名前が変更され、企業が合併し、ワークスペースの名前が変更され、再販業者のパネルには、調整するには十分に安定していないわかりやすいラベルが表示されることがよくあります。リクエストには少なくとも、顧客 ID、グループ ID またはプラン ID、環境、および機密の個人データを公開することなく検索をサポートするメタデータが含まれている必要があります。
2.作成時にポリシーを割り当てる
デフォルトで無制限のキーにはリスクがあります。プロビジョニング リクエストでは、ステータス、許可された使用量、使用量制限、レートまたは同時実行制限、グループ メンバーシップ、およびプラン メタデータを割り当てることができる必要があります。プラットフォームが小さなコントロールのセットから始まる場合でも、データ モデルでポリシーを明示する必要があります。
3.シークレットを一度返します
Complete API キーは通常、作成時またはローテーション時にのみ表示されます。リストおよび詳細エンドポイントには、完全なシークレットではなく、安全なプレフィックスまたは識別子が表示される必要があります。顧客が平文キーを紛失した場合、回復パスは再表示ではなくローテーションである必要があります。
これにより、オンボーディングの設計が変更されます。この製品は、ログを編集し、サポート ツール、分析、URL、スクリーンショット、ブラウザ履歴のキーが誤ってキャプチャされることを回避しながら、顧客またはプロビジョニング サービスに信頼性の高い 1 回限りの配信パスを提供する必要があります。
4.シークレットを安全に保管
パートナー認証情報は、サーバー側のシークレット マネージャーまたは同等の保護されたランタイムに属します。顧客モデルのキーは、ビジネス モデルで必要な場合にのみ、顧客またはプロビジョニング サービスによって、明確な秘密管理ポリシーに基づいて保存される必要があります。認可ヘッダー、ベアラー トークン、平文キー、冪等キー、コールバック シークレット、またはシークレットを含むリクエスト本文のログ記録を避けてください。
5.帰属を直ちに確認
作成後、プロビジョニング システムは、プラットフォーム キー ID、キー プレフィックス、顧客 ID、グループ ID、プラン、ステータス、作成リクエスト ID、およびオペレーターを永続化する必要があります。これにより、サポートは平文の認証情報を必要とせずに、後でキーを見つけることができます。
ライフサイクル管理: 作成、回転、凍結、凍結解除、削除
パートナー API キーのライフサイクル管理は、発行後の認証情報を制御する規律です。実稼働プロビジョニング システムは、作成だけでなくライフサイクル全体をカバーする必要があります。
Rotation はシークレットを置き換えます。一部のプラットフォームでは、古いキーがすぐに無効になり、新しい平文キーが一度返されます。これにより、露出はすぐに減りますが、導入に時間を必要とする顧客の邪魔になる可能性があります。他のシステムは、古いキーと新しいキーが一定期間重複する段階的なローテーションをサポートしています。段階的ローテーションはより寛容ですが、2 つの有効なシークレットをより長く存続させます。
凍結 は、キーの ID、メタデータ、使用履歴、サポート コンテキストを保持しながら、キーによる新しいリクエストの実行を一時的に停止します。調査員はキーを以前のリクエストや監査イベントに関連付けることができるため、インシデント対応中に削除するよりも優れていることがよくあります。
Unfreezing は明示的に行われ、監査される必要があります。その動作が意図的に設計され、可視化されている場合を除き、サポート チケットが終了したり、支払いの再試行が成功したからといって自動的に発生するべきではありません。
削除または取り消しは、アクセスを完全に終了する必要がある場合に適しています。システムは、保持ポリシーに従って、請求、不正行為の調査、監査、顧客とのコミュニケーションに必要な記録を引き続き保持する必要があります。
使用量のリセットは、プラン期間またはプロモーション枠にわたって制限が測定される場合に必要になる場合があります。リセット可能な使用量カウンターを、生涯支出、元帳トランザクション、またはアカウント残高と混同しないでください。
使用制限、支出制限、残高は異なります
プロビジョニング システムは、使用量カウンター、支出制限、請求残高という 3 つの異なる概念があいまいなため、失敗することがよくあります。
- 使用状況カウンタは、期間または有効期間にわたるキーまたはグループの消費量を測定します。
- 支出制限は、顧客キーやグループのハードキャップなどのポリシーのしきい値を定義します。
- 残高は、使用料金を支払うアカウントレベルのウォレット、クレジット、または請求状態です。
一部のプラットフォームでは、顧客向けのキーは所有アカウントの残高を共有しますが、キーごとの制限とグループの制限によって使用が制限されます。つまり、下流の顧客は個別の子残高を持たずに制限を設けることができるということです。この区別は請求書、再販業者のマージン、エラー メッセージ、サポートの説明に影響するため、購入者と実装者はこの区別を明確にする必要があります。
レート制限と支出制限も個別にモデル化する必要があります。レート制限は、インフラストラクチャ、公平性、悪用の境界を保護します。支出制限により、予算と顧客の権利が保護されます。顧客は予算内であるがリクエスト レートを上回っている場合や、レートは下回っているが予算を超えている場合があります。
より広範な予算運用の場合、プロビジョニング データは、アラート、しきい値、計画の適用、財務レポートなどの LLM コスト管理 ワークフローにフィードされる必要があります。
操作の変更には冪等性が必須です
顧客キーを作成、回転、凍結、凍結解除、更新、または削除する API は、再試行を許容する必要があります。リクエストが受け入れられた後、ネットワークに障害が発生します。サーバーの処理中にクライアントがタイムアウトになります。キュー ワーカーは、呼び出しを送信した後、応答を保存する前にクラッシュします。冪等性がないと、再試行により重複キー、重複状態変更、または矛盾するライフサイクル レコードが作成される可能性があります。
通常のパターンは単純です。すべての変更リクエストには、その論理操作の呼び出し元によって生成された一意の冪等キーが含まれます。サーバーは、リクエストのフィンガープリントと結果を、定義された保存期間にわたって保存します。同じ冪等キーが同じ操作に再度使用されると、サーバーは元の結果を返します。同じキーが別のリクエスト本文で再利用される場合、サーバーは競合を返します。
B2B LLM は、パートナー API の POST、PATCH、および DELETE 操作のこのパターンを文書化しています。変更呼び出しには Idempotency-Key が必要で、レコードは 7 日間保持され、同じ論理再試行では元の結果が返され、別のリクエストで同じキーが再利用されると競合が返されます。
実装者にとって、このルールは実用的です。HTTP 試行ごとにではなく、業務運営レベルで冪等性キーを生成します。論理操作が「プラン Pro で顧客 123 のモデル キーを作成する」である場合、その操作が成功するか意図的に破棄されるまで、その操作を再試行するたびに同じ冪等キーが保持される必要があります。
監査証跡とリクエスト履歴
プロビジョニング システムは何が起こったのかを説明できなければなりません。監査証跡には、機密事項を除外しながら、セキュリティとサポートに十分な詳細を備えた成功した管理変更を記録する必要があります。
有用な監査フィールドは次のとおりです:
- タイムスタンプ
- リクエスト ID
- アクターまたはサービス プリンシパル
- アクション (作成、回転、凍結、更新、削除など)
- ターゲット タイプとターゲット ID
- ソース IP または統合オリジン
- ステータス
- 顧客 ID、グループ ID、プラン参照などの安全なメタデータ
監査メタデータには、平文の API キー、ベアラー トークン、完全な認証ヘッダー、べき等キー、コールバック シークレット、リクエスト フィンガープリント、またはリプレイ本体を含めることはできません。キー プレフィックスは検索のサポートに役立ちますが、それらは識別子であり、認証の証明ではありません。
リクエスト履歴は関連していますが、異なります。リクエスト履歴は、どのキーがリクエストを行ったか、リクエストがいつ発生したか、どのモデルが使用されたか、発生したステータス、および追跡できるリクエスト ID など、推論呼び出しの調査をサポートするのに役立ちます。保持ポリシーとプライバシー ポリシーによっては、詳細なプロンプト データと応答データが利用できなかったり、編集されたり、有効期間が短かったりする場合があります。財務調整は、短期保持リクエストの履歴のみに依存すべきではありません。通常は、永続的な残高トランザクション、元帳レコード、または集計エクスポートが必要です。
顧客レベルのレポートが重要な場合は、プロビジョニングされたキーを LLM APIコスト アトリビューションに明確に接続して、使用状況を顧客、チーム、製品、または販売代理店のアカウントにマッピングできるようにする必要があります。
ホワイトラベルとリセラーキーの管理
ホワイト ラベル LLM API キー管理により、運用上の責任がさらに高まります。再販業者または組み込みプラットフォームが顧客関係を所有する一方で、基盤となる LLM API プラットフォームがキーの認証、使用法、制限、リクエスト ルーティングを強制します。
このモデルでは、通常、再販業者は次のことを行う必要があります:
- 独自のバックエンドから顧客モデル キーを作成
- 各キーを再販業者の顧客、ワークスペース、またはプランにマッピングします
- 顧客に表示を許可されている認証情報と使用状況データのみを表示します
- 販売代理店固有の価格設定または権利ルールを適用する
- 顧客が解約した場合、支払いを怠った場合、侵害を報告した場合、またはプランを変更した場合にキーを凍結またはローテーションする
- プロバイダーのコスト、プラットフォームのコスト、顧客に表示される料金を調整する
プロビジョニング プラットフォームは、独自のアカウント モデルが再販業者の顧客モデルと同じであると想定すべきではありません。メタデータ、グループ、使用エンドポイント、トランザクション履歴、監査イベントは、無関係なアカウント データを漏らすことなく、この変換をサポートする必要があります。
エラー処理と顧客対応
プロビジョニング API は契約の一部としてエラーを文書化する必要があります。一般的なケースには、無効な認証情報、認可または IP ホワイトリストの拒否、ターゲットの欠落、無効なリクエスト形式、冪等性の競合、レート制限、使用制限の超過、キーの凍結、キーの削除、残高不足などが含まれます。
クライアントの動作は明示的である必要があります:
- 401: パートナーまたはモデルの認証情報が無効か欠落しています。
- 403: 資格情報はわかっていますが、おそらく IP 制限またはスコープのため、アクションの実行は許可されていません。
- 404: ターゲット キー、グループ、または顧客マッピングが存在しないか、呼び出し元に表示されません。
- 409: リクエストは既存の状態と競合します。多くの場合、冪等キーが誤って再利用されたことが原因です。
- 422: リクエストは構造的には有効 JSON ですが、検証ルールに違反しています。
- 429: レート制限または支出制限に達しました。
支出制限の失敗には特別な注意が必要です。顧客向けのモデル キーがハード リミットに達すると、推論リクエストが突然失敗し始める可能性があります。プラットフォームは、エラー コード、再試行動作、リセットのタイミング、およびしきい値アラートまたはコールバックが枯渇する前に利用可能かどうかを定義する必要があります。ソフト制限とアラートにより、チームは対応する時間が得られますが、下流のワークフローが必要になります。ハード制限により予算の超過は防止されますが、実稼働ワークロードが中断される可能性があります。
コールバック、ポーリング、および非同期結果
一部のプロビジョニングおよびレポート操作は同期して完了します。特にシステムが大規模なエクスポート、遅延した元帳更新、残高アラート、またはリクエスト完了イベントを処理する場合、ポーリングまたはコールバックが必要になる場合もあります。
コールバックは少なくとも 1 回の配信として扱われる必要があります。コンシューマは、重複排除、署名検証、再試行処理、タイムスタンプ チェック、配信不能処理のために安定したイベント ID を必要とします。コールバック シークレットは、他のシークレットと同様にローテーション可能であり、保存できる必要があります。送信者からの再試行では、重複した元帳エントリ、重複した顧客通知、または繰り返しの修復アクションが作成されるべきではありません。
ポーリングは、特にパートナーが調整ジョブを明示的に制御したい場合に、非同期結果に対して引き続き役立ちます。成熟したプラットフォームは、タイムリーなイベントのコールバックと決定的な回復のためのポーリングの両方をサポートする場合があります。
機械可読な契約とバージョン管理
API をプロビジョニングするパートナーには、OpenAPI などの機械読み取り可能な契約が必要です。パートナーは、本番展開前にクライアントを生成し、リクエストとレスポンスの形状を検証し、重大な変更を検出する必要があります。
契約には、必要なヘッダー、冪等性の動作、認証スキーム、10 進数の処理、ページネーション、フィルタリング、ステータス値、エラー応答、コールバック署名、および保持の期待値を文書化する必要があります。金額および使用量の値は、支出制限、残りの予算、請求書、調整レポートの丸めドリフトを避けるために、2 進浮動小数点数ではなく、10 進数の文字列または固定精度の小数として表す必要があります。
パートナーが依存するバージョンの動作。応答形状の小さな変更が、文書化されていない場合、顧客のオンボーディング、請求書のエクスポート、またはサポート ツールに支障をきたす可能性があります。
避けるべきよくある間違い
最もリスクの高い失敗は、パートナーまたはアカウントレベルの認証情報が信頼できるサーバー環境の外に公開されることです。認証情報が漏洩すると、攻撃者は権限に応じて顧客キーを作成、ローテーション、凍結、削除できる可能性があります。最小限の権限、実際的な場合は IP 制限、機密管理、監視、およびインシデント対応手順を使用します。
もう 1 つのよくある失敗は、すべての顧客に対して 1 つの共有モデル キーを使用することです。これは最初は簡単ですが、帰属を破壊します。サポートでは、どの顧客が使用量を生成したかを知ることができません。財務部門はテナントごとの使用状況を調整できません。セキュリティでは、全員を凍結せずに 1 人の顧客を凍結することはできません。虐待調査は推測の域を出ません。
冪等性を持たないキーの作成も重大な運用上のバグです。オンボーディング中のタイムアウトによって 2 つのアクティブな顧客キーが作成されたり、リセラーがどのキーが提供されたかわからないままになったりすることはあってはならない。
チームは、移行計画なしでキーをローテーションしたり、調査コンテキストを保存する前にキーを削除したり、通貨値を浮動小数点数として解析したり、唯一の財務記録としてリクエスト履歴に依存したり、グループ ID が無効な場合にグループ化されていないキーに黙ってフォールバックしたりする場合にも問題に遭遇します。
最後に、プロビジョニングを単なる製品チェックリストにしないでください。購入者は、認証情報の分離、ライフサイクル管理、テナントの分離、使用量の帰属、支出の強制、安全な再試行、監査可能性、調整などのガバナンス モデルを理解する必要があります。
顧客キーのプロビジョニングについてパートナー API を評価する方法
LLM プラットフォームを比較する場合は、エンドポイントがキーを作成できるかどうかだけを尋ねるのではなく、運用に関する質問をしてください。
- プラットフォームはパートナー/管理者の認証情報をモデル推論キーから分離しますか?
- キーはグループ、顧客、プラン、環境、またはメタデータに割り当てることができますか?
- 作成、更新、回転、凍結、凍結解除、削除、リストの操作は API? を通じて実行できますか?
- 変更操作はべき等であり、保持と競合の動作が定義されていますか?
- 完全なシークレットは 1 回だけ表示され、安全なプレフィックスを検索に使用できますか?
- 使用量、残高制限、支出、リクエスト履歴、残高、トランザクションを照会できますか?
- 通貨値は 10 進数でも安全ですか?
- 監査イベントは管理の変更に利用できますか?
- サポート チームはシークレットを見ずにプレフィックスでキーを識別できますか?
- エラー、レート制限、支出制限の動作、および再試行ルールは文書化されていますか?
- 機械で読み取り可能な API 契約はありますか?
- コールバックまたはポーリングは非同期ワークフローと調整をサポートできますか?
B2B LLM のパートナー API は、この方向性の一例です。これは、キーとグループのサーバー間管理、キーのライフサイクル操作、使用状況とリクエスト履歴へのアクセス、残高とトランザクションの取得、監査イベントの取得、非同期結果のポーリングをサポートしています。購入者の重要な教訓は、単一のベンダーよりも広範囲にわたります。主要なプロビジョニングは、単一のエンドポイントとしてではなく、ガバナンスおよび運用能力として評価されるべきです。
実用的な結論
LLM アクセスがビジネス ワークフロー、リセラー製品、カスタマー ポータル、ボット プラットフォーム、または内部 AI プログラムに組み込まれている場合、LLM プラットフォーム用の顧客 API キーのプロビジョニングが必要になります。適切な設計では、特権プロビジョニング資格情報を顧客向けのモデル キーから分離し、各キーを永続的な所有者またはグループに割り当て、使用量と支出の制御を適用し、ライフサイクル アクションを安全に自動化します。
まず、プリンシパル モデルと主要な分類を定義します。次に、キーの作成、回転、凍結、凍結解除、削除、使用、監査、調整のワークフローを一緒に設計します。変更操作には冪等性が必要です。すべての資格情報をシークレットとして扱います。サポートと財務のために十分な運用コンテキストを保持します。顧客が直面するエラーを予測可能にします。
その結果は、オンボーディングの高速化だけではありません。これは制御可能な LLM アクセス レイヤであり、顧客をプログラムでプロビジョニングし、使用状況を正しく特定し、制限を強制し、インシデントを封じ込めることができ、API キーの処理を手動のサポート プロセスに変えることなくビジネスを拡大できます。