管理
管理 API
管理トークンを使って組織残高、組織 API Key、キー単位の使用量と請求を管理・取得します。
概要
Management API を使うと、通常の推論用 API Key を使わずに、組織残高の取得、組織 API Key の管理、キー単位の使用量・請求情報の取得ができます。
管理トークンは Dashboard → API → Management Tokens で発行・ローテーションできます。
Authorization: Bearer mt-your-management-token管理トークンは推論用 API Key とは異なります。mt-... は /v1/management/* 用、sk-... は /v1/responses などの推論エンドポイント用です。
利用できるエンドポイント
| エンドポイント | メソッド | 説明 |
|---|---|---|
/v1/management/balance | GET | 現在の組織残高合計を取得 |
/v1/management/api-keys | GET | 現在の組織に属するユーザー API Key を一覧表示 |
/v1/management/api-keys | POST | 新しいユーザー API Key を作成 |
/v1/management/api-keys/{keyId} | PATCH | 名前、利用上限、許可モデル、有効期限、状態を更新 |
/v1/management/api-keys/{keyId}/usage | GET | 指定した Key の利用明細をページネーション付きで取得 |
/v1/management/api-keys/{keyId}/billing | GET | 指定した Key の集計済み請求内訳を取得 |
利用フィルタ
GET /v1/management/api-keys/{keyId}/usage では以下の query パラメータを利用できます。
| パラメータ | 型 | 既定値 / 制約 | 説明 |
|---|---|---|---|
page | integer | 既定値 1、最小 1 | 1 始まりのページ番号 |
limit | integer | 既定値 50、最小 1、最大 100 | 1 ページあたりの件数 |
model | string | 最大長 100 | リクエスト時に指定されたモデル名 |
modelVendor | string | 最大長 100 | 公開モデルのベンダー名 |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
startDate | string | - | 開始日時（含む）。タイムゾーン付き RFC3339 または YYYY-MM-DD を受け付けます |
endDate | string | - | 終了日時（含む）。タイムゾーン付き RFC3339 または YYYY-MM-DD を受け付けます |
startDate と endDate を同時に指定する場合、startDate は endDate 以下である必要があります。
API Key リクエスト本文
POST /v1/management/api-keys
| フィールド | 型 | 既定値 / 制約 | 説明 |
|---|---|---|---|
name | string | 任意、既定値 Default Key、長さ 1-50 | 表示名。サーバー側で前後空白が取り除かれます |
limitAmount | number | string | null | 0–100000 USD | null は無制限、0 は支出不可です。10 進文字列は小数点以下 6 桁まで指定できます。 作成時に省略すると無制限になります。 |
limitCurrency | enum | 既定 USD | USD のみです。CNY を送信すると 400 currency_retired が返されます。 |
models | string[] | 既定値 [] | 任意のモデル許可リスト |
deliveryPolicy | string | null | auto, verified, official, null | null はワークスペースの配信ポリシーを継承します。 |
expiresAt | string | null | RFC3339 datetime | null は期限なしを意味します |
PATCH /v1/management/api-keys/{keyId}
| フィールド | 型 | 既定値 / 制約 | 説明 |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | 長さ 1-50 | 更新後の表示名 |
limitAmount | number | string | null | 0–100000 USD | null は無制限、0 は支出不可です。10 進文字列は小数点以下 6 桁まで指定できます。 |
limitCurrency | enum | 既定 USD | USD のみです。CNY を送信すると 400 currency_retired が返されます。 指定する場合は limitAmount も必要です。 |
models | string[] | - | 更新後のモデル許可リスト |
deliveryPolicy | string | null | auto, verified, official, null | null はワークスペースの配信ポリシーを継承します。 |
expiresAt | string | null | RFC3339 datetime | null は有効期限を解除します |
PATCH リクエストでは少なくとも 1 つのフィールドを指定する必要があります。
金額フィールド
- Management API の金額リクエストおよびレスポンスフィールドは USD のみをサポートします。
limitCurrencyの既定値はUSDです。CNYを送信すると400 currency_retiredが返されます。
レポートの意味
modelは、呼び出し元が要求した公開 model を指します。modelVendorは、隠れた互換ルートではなく、公開 model vendor を指します。sceneは、endpoint または task type から導出される公開リクエストシーンです。
レスポンスには公開可能な Billing / Reporting 項目のみが含まれ、非公開のプロバイダー詳細は公開されません。
/usageの各明細には、基になるリクエストの精算完了後にbilling_transaction_idが含まれる場合があります。リクエスト単位の照合にはrequest_id+billing_transaction_idを使用してください。
請求のページネーションに関する注意
/usage はページネーション対応です。/billing は現在、集計済み請求内訳を返すエンドポイントであり、page / limit 型のページネーション情報は返しません。行レベルの明細が必要な場合は /usage を利用してください。
クイック例
まずは現在の管理トークンで組織残高を確認します。
リクエスト
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"次に、同じ管理トークンで参照可能な API Keys を一覧します。
リクエスト
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"レスポンス
{
"object": "list",
"data": [
{
"id": "key_abc123def456",
"name": "Backend Worker",
"key_prefix": "sk-abc123...",
"status": "active",
"limit_amount": 500.0,
"limit_amount_decimal": "500",
"used_amount": 148.25,
"used_amount_decimal": "148.25",
"models": [
"gpt-4o-mini",
"claude-3-7-sonnet"
],
"expires_at": "2026-04-30T00:00:00.000Z",
"last_used_at": "2026-03-27T08:12:45.000Z",
"created_at": "2026-03-01T10:00:00.000Z",
"delivery_policy": null
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}