Provisioning Keys

provisioning key 讓你的後端能夠以程式化方式建立和管理 推論 API 金鑰 ——無需任何人登入 Console。非常適合為每個終端使用者、每台裝置或每個 CI 任務簽發一個金鑰的 SaaS 產品。

運作原理

1. owner 或 admin 在以下位置建立 provisioning key： Console → Provisioning Keys. 它帶有前綴 sk-syn-prov-.
2. 你的後端呼叫 /api/provisioning/* 端點，使用該金鑰建立推論金鑰（前綴 sk-syn-).
3. 每個推論金鑰的作用範圍限定於同一個 workspace，並可附帶 USD 消費上限和不透明的 metadata 標籤。
4. 將推論金鑰交付給你的使用者。可隨時單獨撤銷其中任意一個——刪除 provisioning key 不會 影響它已經建立的推論金鑰。

驗證

將 provisioning key 作為 Bearer token 傳遞。它適用於 僅 於 /api/provisioning/* ——provisioning key 無法發起推理呼叫，一般的 inference key 也無法呼叫這些管理端點（兩種情況都會返回 401 wrong_key_kind).

Authorization: Bearer sk-syn-prov-...

建立推論金鑰

POST /api/provisioning/keys

curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Device abc-123",
    "quota": 5.0,
    "allowed_models": "claude-haiku-4-5",
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/provisioning/keys",
    headers={"Authorization": "Bearer sk-syn-prov-..."},
    json={
        "name": "Device abc-123",
        "quota": 5.0,
        "allowed_models": "claude-haiku-4-5",
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["key"]  # full key — shown only once

回應會在以下欄位中傳回完整的金鑰： key 欄位 僅一次. 請立即儲存——之後無法再次取得。

{
  "id": 42,
  "key": "sk-syn-d4f0...e91b",
  "key_prefix": "sk-syn-d4f0...",
  "name": "Device abc-123",
  "kind": "inference",
  "created_via": "provisioning_api",
  "parent_provisioning_id": 7,
  "workspace_id": 11,
  "quota_usd": 5.0,
  "unlimited_quota": false,
  "allowed_models": "claude-haiku-4-5",
  "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
  "created_at": "2026-06-01T12:00:00Z"
}

列出推論金鑰

GET /api/provisioning/keys

列出該 workspace 中的每一個推論金鑰。可按任意 metadata 欄位進行篩選： ?metadata.<key>=<value>；多個篩選條件以 AND 組合。

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

# only keys tagged tenant_id=acme
curl "https://synthorai.io/api/provisioning/keys?metadata.tenant_id=acme" \
  -H "Authorization: Bearer sk-syn-prov-..."

取得、更新與刪除

透過其數字型的 id：

• GET /api/provisioning/keys/{id} ——取得單個金鑰。
• PATCH /api/provisioning/keys/{id} ——更新 name, quota, status, allowed_models, ip_whitelist, expires_at, include_byok_in_limit, 或 metadata. 其中 kind 和血緣欄位無法變更。
• DELETE /api/provisioning/keys/{id} ——撤銷金鑰。立即生效。

# disable a key (status 2 = disabled)
curl -X PATCH https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{ "status": 2 }'

# delete a key
curl -X DELETE https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..."

配額與消費控制

quota 是每個推論金鑰的 USD 上限。用量在每次請求後計量，因此在高並行下，金鑰在短暫的結算視窗內可能略微超出其上限——對高價值模型設定上限時請預留少量緩衝。可從以下位置讀取金鑰的目前消費 used_usd 中讀取，它出現在列出 / 取得回應裡。

為每個金鑰設定美元上限?LLM API cost calculator 能把客戶的預期 token 用量換算成每月支出金額,你可以把它設為 quota。