クイックスタート

認証ガイドに従ってサインインし、管理キーページを開いて管理キーを作成します。標準のアプリケーションキーとは別に保管してください。Platform Managementエンドポイントにのみ、Bearerトークンとして送信してください。

標準 API キーはキーまたはガードレール管理エンドポイントを呼び出すことができません。有効な管理キーでも、所有者が必要なアカウントロールを持っていない場合は 403 Forbidden を受け取ることがあります。

管理キーのアカウントから参照可能なキーを確認するには、GET /api/v1/keys を使用してください：

後続の取得・更新・失効・ガードレール割り当てリクエストには、返却された公開識別子を使用してください。キー名やマスクされたトークンからアクセス権を推測しないでください。

POST /api/v1/keysでアプリケーションキーを作成します。完全なシークレットは作成レスポンスでのみ返されるため、そのレスポンスを破棄する前にシークレットマネージャーに保存してください。ローテーションでは、代替キーを作成してアプリケーションにデプロイし、トラフィックを確認してから古いキーを無効化します。

credit_limit_windows は 1h、1d、7d のローリング支出上限の任意の組み合わせを受け付けます。設定されたウィンドウのいずれかが上限に達した場合、そのキーを使用した呼び出しは、使用量がウィンドウから外れるまで 429 Too Many Requests を返します。キーを更新する際にすべてのローリング上限をクリアするには、空のオブジェクトを送信してください。

作成リクエストで支出上限のすべてのフィールドと guardrail_id を省略すると、新しいキーにはワークスペースのガバナンス既定値が適用されます。明示的な上限、ローリングウィンドウ、またはガードレールを指定すると、その既定の選択が置き換えられます。ネイティブ上限を無制限にするには、credit_limit_cents: null を送信してください。リセット間隔を指定せずに金額を指定した場合は、生涯上限のままです。更新時にワークスペースの既定値が再適用されることはなく、既定値を変更しても既存のキーは変更されません。

作成と更新は、完全な key:value 文字列の配列 tags を受け付けます。一覧・取得・作成・更新のレスポンスは配列全体を返します。PATCH は配列を置換し、tags を省略すると保持します。キーは1–32文字、値は1–64文字で、コロンはちょうど1つ、空白文字は禁止です。プリセットを含め最大20個の異なるタグを指定できます。不正な形式やプリセットの競合はタグ検証エラー付きの 422、配列以外や文字列以外の要素は 400 を返します。

用途タグは usage:developer または usage:service のいずれか1つが必須です。Management API での作成時に用途が未指定なら、tags: [] の場合も usage:service を追加します。Dashboard での作成や用途を含まないタグ更新では usage:developer を使用します。既存キーは Developer として移行します。環境は任意で、env:production、env:staging、env:dev のうち最大1つを指定できます（env:prod は不可）。

Dashboard の作成・編集では、用途と環境のクイック選択、カスタムタグ、現在のワークスペースで削除されていない標準キーからの候補を提供します。一覧には値が表示され、ホバーすると完全なタグが表示されます。タグはキーの所有権、可視性、権限を変更しません。タグによってキーを共有タグ予算に関連付けることができます。

ワークスペース管理者は Team のメンバー予算フォームで、メンバーの必須タグを設定します。必須タグは team:growth など、大文字・小文字を区別するカスタムタグです。usage: と env: の名前空間は予約されています。メンバーには最大19個の必須タグを設定でき、各キーのタグ総数の上限は引き続き20個です。

新しい標準キーには、そのワークスペースで所有者に設定された必須タグが自動的に含まれます。作成時は送信されたタグと必須タグを結合してから検証します。たとえば、メンバーに team:growth が必須の場合、Management API の作成リクエストで tags: ["project:chatbot"] を指定すると、project:chatbot、team:growth、既定の usage:service が返されます。

tags を指定する PATCH は、すべての必須タグを保持する必要があります。必須タグを削除すると、呼び出し元が管理者でも、不足しているタグを示す検証エラーとともに 422 が返されます。tags を省略すると、キーのタグは保持されます。メンバーは通常のタグを引き続き追加・削除できます。

必須タグを削除するには、管理者が Team でメンバーの設定を変更します。保存すると、そのメンバーの既存のすべての標準キーに新しい必須タグが追加され、解除された必須タグは削除されます。他のタグは保持されます。無効化・期限切れのキーも対象ですが、削除済みのキーは除外されます。いずれかのキーが最終的なタグ集合を受け入れられない場合、保存全体が失敗し、修正が必要なキーがフォームに表示されます。

タグ予算は各キーの現在のタグを使用します。必須タグを変更すると、現在の期間に発生済みの支出の予算帰属も変わります。必須タグを追加した時点で、そのタグの予算を使い切る場合があります。既存メンバーの必須タグは初期状態では空で、管理者が設定を保存するまで既存のキーは変更されません。

Guardrail は、モデル、プロバイダー、および支出制御のための再利用可能なアカウントポリシーです。/api/v1/guardrails を通じてポリシーを管理し、/api/v1/guardrail_assignments を使用して添付または削除します。拒否されたアサインメントは、Guardrail なしで暗黙的に続行するのではなく、ポリシーまたは所有権の失敗として扱ってください。

上限が正の block モードのガードレールを作成し、その guardrail_id と dept:ml などの大文字と小文字を区別する tag を割り当てます。対象は api_token_id、account_user_id、tag のいずれか 1 つです。タグ予算には管理者権限が必要です。無効な予算は制限を適用しません。管理リクエストは予算を消費しません。

予算は標準キーの現在のタグを集計し、削除済み、無効、期限切れのキーの支出も含みます。タグの追加と削除で、そのキーの現在期間の支出が移動します。予算の作成や再作成で支出はリセットされません。キー数は削除済みキーを除きます。一致するすべての予算がリクエストを許可する必要があり、拒否時は 403 とタグ名を返します。

credit_limit_reset_interval が null の場合は無期限です。他の期間は UTC を使用します。警告しきい値の初期値は 80、範囲は 1～100 です。ガードレールの直接更新はすべての割り当てに適用されます。ダッシュボードでタグ予算を編集する場合は先にポリシーを複製します。

受け入れ時は予約額を確認します。確定額は予約額を超え、使用率が 100% を超えて以後の有料リクエストを拒否する場合があります。ログはログ作成時刻を、保留中のタスクとバッチはそれぞれの作成時刻を使用します。前の期間に受け付けたタスクが後の期間に確定することがあります。