管理金鑰

管理金鑰讓你用自己的程式碼管理工作區：為客戶或裝置建立推論金鑰並設定上限，讀取用量、日誌和設定。它不能呼叫模型。

建立管理金鑰

1. 在主控台開啟 API 金鑰 › 管理金鑰，點選建立管理金鑰。管理員和工作區擁有者可以建立。
2. 選擇金鑰歸誰所有、帶哪些權限範圍。
3. 複製金鑰。它以 sk-syn-admin- 開頭，只顯示一次。

權限範圍

一個權限範圍對應管理 API 的一部分。寫入權限包含對應的讀取權限。金鑰沒有相應的權限範圍時，請求會回傳 403 insufficient_scope。

金鑰歸誰所有

• 你。你離開工作區後，金鑰會被停用。你還在工作區但不再是管理員時，請求會回傳 403 key_creator_not_authorized。
• 工作區。建立者離開或角色變更後，金鑰照常可用。適合 CI 和整合。建立者離開時，這把金鑰會連同用它建立的推論金鑰一起移交給工作區擁有者，全部照常可用。

歸屬在建立金鑰時選定，之後無法變更。

驗證

把金鑰當作 Bearer token 傳送。管理金鑰只能用於管理 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> 可依任意 metadata 欄位篩選。結果分頁回傳：把 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} 回傳單一金鑰。
• 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-..."

管理金鑰代表一位成員操作：通常是它的建立者；如果金鑰屬於工作區且建立者已離開，則代表工作區擁有者。它只能修改、輪換和刪除這位成員的金鑰，包括它自己建立的；對其他成員的金鑰會回傳 403 not_key_creator，用擁有者的管理金鑰也一樣。在專屬執行個體上，工作區的任何管理金鑰都能管理所有成員的金鑰，和管理員在主控台中能做的一樣。管理員停用的金鑰只有管理員能重新啟用，其他人啟用會回傳 403 disabled_by_admin。

上限和花費

limit_usd 是金鑰最多能花多少，used_usd 是已經花了多少。達到上限後，status 會變成 limit_reached，請求會被拒絕，直到你調高上限或週期重設。

正在為每把金鑰訂花費上限？用 LLM API 成本計算機 把客戶預估的 token 用量換算成每月金額，直接填進 limit_usd。

錯誤

錯誤沿用管理 API 的統一格式：error.code 說明原因，error.message 說明如何處理；在 /api/provisioning/keys 上，同樣的錯誤碼會放在 error.type 中。以下是管理金鑰和金鑰 API 特有的錯誤碼。

Provisioning 金鑰和 /api/provisioning

管理金鑰推出之前簽發的金鑰（sk-syn-prov-）仍可使用，帶有 keys.read 和 keys.write 兩個權限範圍。舊路徑 /api/provisioning/keys 仍然可用，欄位名稱維持原樣（quota、status）。新的整合請用 /api/v1/keys。

管理 API 還涵蓋帳單、請求日誌、提示詞和工作區設定，詳見 API 總覽和 OpenAPI 文件。