管理キー

管理キーは、自分のコードからワークスペースを管理するためのキーです。顧客やデバイスが使う推論キーを作成して上限を設定し、使用量、ログ、設定を読み取れます。モデルの呼び出しには使えません。

管理キーを作成する

1. コンソールで API キー › 管理キーを開き、管理キーを作成を選びます。作成できるのは管理者とワークスペースの所有者です。
2. キーの所有者と、付与するスコープを選びます。
3. キーをコピーします。sk-syn-admin- で始まり、表示されるのは一度だけです。

スコープ

スコープ 1 つにつき、管理 API の一部が使えるようになります。書き込みスコープには、対応する読み取りスコープが含まれます。必要なスコープがないキーでのリクエストには 403 insufficient_scope が返ります。

キーの所有者

• あなた。ワークスペースから退出すると、キーは無効になります。ワークスペースに残ったまま管理者でなくなった場合は、リクエストに 403 key_creator_not_authorized が返ります。
• ワークスペース。作成者が退出しても、ロールが変わっても、キーは使い続けられます。CI や連携にはこちらを使います。作成者が退出すると、このキーと、このキーで作成した推論キーはワークスペースの所有者に引き継がれ、そのまま使えます。

所有者はキーの作成時に選びます。あとから変更することはできません。

認証

キーは Bearer トークンとして送ります。管理キーが使えるのは管理 API だけです。/v1/ 以下のモデルエンドポイントは管理キーを受け付けず、管理 API は推論キー（sk-syn-）を 401 wrong_key_kind で拒否します。

Authorization: Bearer sk-syn-admin-...

推論キーを作成する

POST /api/v1/keys

curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: device-abc-123" \
  -d '{
    "name": "Device abc-123",
    "limit_usd": 5.0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/v1/keys",
    headers={
        "Authorization": "Bearer sk-syn-admin-...",
        "Idempotency-Key": "device-abc-123",
    },
    json={
        "name": "Device abc-123",
        "limit_usd": 5.0,
        "limit_reset": "monthly",
        "allowed_models": ["claude-haiku-4-5"],
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["data"]["key"]  # full key - shown only once

レスポンスの key にキーの全体が入ります。返るのはこの 一度だけなので、その場で保存してください。以降の取得では key_prefix しか返りません。

{
  "data": {
    "id": 42,
    "key": "sk-syn-d4f0...e91b",
    "key_prefix": "sk-syn-d4f0...",
    "name": "Device abc-123",
    "enabled": true,
    "status": "enabled",
    "limit_usd": 5.0,
    "used_usd": 0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "ip_allowlist": [],
    "expires_at": null,
    "include_byok_in_limit": true,
    "rate_limit": { "rpm": 0, "tpm": 0 },
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
    "created_via": "provisioning_api",
    "created_at": "2026-10-01T12:00:00Z"
  },
  "meta": { "request_id": "01a1..." }
}

作成を安全に再試行するには、Idempotency-Key ヘッダーを付けて送ります。同じ値で再送すると最初のレスポンスが返りますが、シークレットは含まれません。同じキーには 24 時間このレスポンスが返り、その間にリソースを削除していても変わりません。作り直すときは新しいキーを使ってください。

キーの一覧と絞り込み

GET /api/v1/keys

?metadata.<name>=<value> で、メタデータの任意のフィールドによる絞り込みができます。結果はページ単位で返ります。次のページを取得するには、meta.next_cursor の値を cursor に渡します。

# all keys
curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..."

# only keys tagged tenant_id=acme, 50 at a time
curl "https://synthorai.io/api/v1/keys?metadata.tenant_id=acme&limit=50" \
  -H "Authorization: Bearer sk-syn-admin-..."

取得、変更、ローテーション、削除

• GET /api/v1/keys/{id} は、キーを 1 件返します。
• PATCH /api/v1/keys/{id} は、送ったフィールドだけを変更します。"enabled": false を送ると、キーを削除せずに停止できます。
• POST /api/v1/keys/{id}/rotate は、キーに新しいシークレットを発行します。古いシークレットはすぐに無効になります。
• DELETE /api/v1/keys/{id} は、キーを削除します。そのキーを使うリクエストには、すぐに 401 が返ります。

# stop a key without deleting it
curl -X PATCH https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# give it a new secret
curl -X POST https://synthorai.io/api/v1/keys/42/rotate \
  -H "Authorization: Bearer sk-syn-admin-..."

# delete it
curl -X DELETE https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..."

管理キーは 1 人のメンバーの代理として動作します。代理するのはキーの作成者で、ワークスペースのキーの場合、作成者が退出した後は所有者になります。変更、ローテーション、削除ができるのはそのメンバーのキーだけで、このキーで作成したキーも含まれます。他のメンバーのキーには、所有者の管理キーを使っても 403 not_key_creator が返ります。専用インスタンスでは、管理者がコンソールでできるのと同じく、ワークスペースのどの管理キーでも全メンバーのキーを管理できます。管理者が無効にしたキーを再び有効にできるのは管理者だけで、ほかの人が有効にしようとすると 403 disabled_by_admin が返ります。

上限と利用額

limit_usd はキーが使える金額、used_usd はこれまでに使った金額です。上限に達すると status が limit_reached になり、上限を引き上げるか期間がリセットされるまでリクエストは拒否されます。

キーごとの利用上限を決めるときは、 LLM API コスト計算ツール が使えます。顧客の想定トークン量を月額に換算できるので、その金額を limit_usd に設定できます。

エラー

エラーは管理 API 共通の形式で返ります。error.code が原因を、error.message が対処方法を示します。/api/provisioning/keys では、同じコードが error.type に入ります。管理キーとキー API に固有のコードは次のとおりです。

プロビジョニングキーと /api/provisioning

管理キーの導入前に発行されたキー（sk-syn-prov-）は、keys.read と keys.write のスコープを持つキーとして引き続き使えます。以前のアドレス /api/provisioning/keys も、独自のフィールド名（quota、status）のまま提供しています。新しく連携を作る場合は /api/v1/keys を使ってください。

管理 API では、請求、リクエストログ、プロンプト、ワークスペース設定も扱えます。API の概要と OpenAPI ドキュメントを参照してください。