ドキュメント

ドキュメント

管理 API

管理キーを使うと、自社のシステムからアカウントの API キーを API 経由で作成・グループ化・上限設定・失効でき、利用額も読み取れます。モデルの呼び出しはできません。

用途

顧客、チーム、ユーザーごとに専用の API キーを発行し、顧客ごとのキーをグループにまとめ、グループの利用額に上限を設けて、キー別・グループ別に費用を読み戻す連携があります。キーが少ないうちは API キーページでの操作で十分です。数が増えたら、管理キーを使ってスクリプトや自社の管理ツールから同じことを API で行えます。

管理キーは API キーとは別の認証情報です。API キーが使える場所では使えず、/v1/chat/completions、/v1/messages をはじめとするモデルのルートは呼び出せません。使えるのは /v1/management/ だけで、API キーはそこでは使えません。

管理キーを作成する

  • API キーページを開き、いちばん下までスクロールします。「管理キー」の下で「新しい管理キー」を選びます。このブロックは、開くまで折りたたまれています。
  • キーに名前を付けます(例: billing sync)。どのプログラムが変更したかがページに表示されます。
  • 呼び出しを許可するアドレスを 1 行に 1 件入力します。203.0.113.7 のような単一のアドレスも、203.0.113.0/24 のような範囲も指定できます。許可リストがないと、キーを持つ人なら誰でも使えます。リストを空のままにすると、ダイアログで警告が表示されます。
  • キーが表示されたらコピーしてください。表示されるのは一度だけです。Kunavo が保存するのはそのハッシュだけです。

1 つのアカウントで有効にできる管理キーは同時に 2 件までです。新しく作るには、どちらか 1 件を失効させてください。

呼び出し方

キーを Bearer トークンとして https://api.kunavo.com/v1/management に送ります。管理キーはブラウザーからの呼び出しを受け付けません。レスポンスに CORS ヘッダーが付かないため、他のサイトのページからは呼び出せません。キーはサーバーに置き、フロントエンドのコードには決して入れないでください。

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

レスポンスは JSON です。エラーの形式は API のほかの部分と同じで、error オブジェクトに message、type、code、該当する場合は問題のある param が含まれます。返されるステータスは次のとおりです。

ステータス意味
401キーがない、誤っている、または失効しているか、アカウントが停止中または審査中です。
403キーに IP 許可リストが設定されていて、リクエストが許可リストにないアドレスから送られました。
404グループまたはキーが存在しない、削除済み、または別のアカウントのものです。3 つとも同じ応答を返すため、別のアカウントの ID を試しても何も分かりません。
409変更がアカウントの状態と矛盾しています。グループ名がすでに使われている、キーが失効済み、またはアカウントの有効なキーが上限の 500 件に達している場合です。
429このキーは直近 1 分間に 60 件のリクエストを送っています。Retry-After ヘッダーに待つべき秒数が示されます。

グループ

GET /v1/management/groups はアカウントのグループを、それぞれの月間上限と有効なキーの数とともに一覧します。POST はグループを作成します。monthly_limit_usd は省略でき、すでに使われている名前は 409 になります。PATCH /v1/management/groups/{id} は名前または上限を変更します。null を送ると上限なし、0 を送るとキーを 1 件も失効させずにグループ内のすべてのキーを一時停止します。DELETE はグループを削除します。そのグループの呼び出しは、使用量ページではグループ名が残ります。グループ内のキーは有効なままグループ未設定になりますが、?revoke_keys=true を付けるとそれらのキーも失効します。

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001", "monthly_limit_usd": 50}'

キー

GET /v1/management/keys はキーを新しい順に一覧します。1 ページは 50 件で、limit で最大 100 件にできます。status の既定値は active で、revoked や all も指定できます。group_id を指定すると、一覧を 1 つのグループに絞り込めます。has_more が true のときは、next_after に after を渡すと次のページを読み取れます。キーの平文が一覧に出ることはありません。

POST /v1/management/keys は、名前と、必要に応じて group_id、monthly_limit_usd、ip_allowlist を指定してキーを作成します。平文はレスポンスの key フィールドに一度だけ含まれます。POST を繰り返すとキーがもう 1 件作られるため、再試行する前にキーを一覧して、その名前のキーがないか確認してください。

curl https://api.kunavo.com/v1/management/keys \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'

PATCH /v1/management/keys/{id} は、キーの名前、グループ、上限、許可リストを変更します。group_id に null を指定すると、キーをグループから外せます。DELETE はキーを失効させます。すでに失効したキーをもう一度失効させてもエラーにはなりません。失効したキーは変更できません。

curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

使用量

GET /v1/management/usage はアカウント全体の使用量を最大 90 日分(UTC の日)まで報告し、GET /v1/usage は 1 つのキーの使用量を報告します。group_by には group、api_key、model、day を自由に組み合わせて指定でき、既定値は api_key です。数値の意味は使用量ページと同じです。呼び出しは、その時点でキーが属していたグループに集計され、失敗した呼び出しは無料で、ある期間の合計は同じ日付の CSV エクスポートの合計とセント単位まで一致します。group_id と api_key_id で、レポートを 1 つのグループまたは 1 つのキーに絞り込めます。

curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"
日付は UTC の暦日で、開始日と終了日の両方を含みます。今日より後の end_date は今日として扱われ、レスポンスには実際に使われた終了日が返されます。

安全に管理する

  • 許可リストを設定してください。サーバーのアドレスからしか使えないキーは、盗まれても悪用されにくくなります。
  • キーは、ツールを実行するサーバー上のシークレットストアに保管してください。ブラウザー、モバイルアプリ、リポジトリには決して置かないでください。
  • 漏えいした場合は、API キーページの下部で失効させるか、そのキーに対して DELETE を呼び出してください。失効のダイアログでは、そのキーが作成したキーもあわせて失効できます。
  • キーが API 経由で行ったすべての変更は、API キーページの「管理キー」の下に、時刻、送信元のアドレス、変更を行ったキーとともに、直近 50 件まで表示されます。そのページで手動で行った変更は表示されません。
  • アカウントが停止または審査中になったとき、およびキーが失効したときは、キーは自動的に使えなくなります。

管理キーで送れるリクエストは 1 分あたり 60 件までです。変更 1 件につきリクエストは 1 回にし、一覧は 1 件ずつではなくページ単位で読み取ってください。

グループ、その月間上限、数値の数え方はキーのグループのページで説明しています。使用量の数値は使用量ページと同じです。