Provisioning Keys

provisioning key 让你的后端能够以编程方式创建和管理 推理 API 密钥 ——无需任何人登录 Console。非常适合为每个终端客户、每台设备或每个 CI 任务签发一个密钥的 SaaS 产品。

⚠

provisioning key 可以创建、修改和删除其 workspace 中的任意推理密钥。请将其视为 admin 凭证：仅在服务器端存储，绝不要分发到浏览器或移动客户端。

工作原理

owner 或 admin 在以下位置创建 provisioning key： Console → Provisioning Keys. 它带有前缀 sk-syn-prov-.
你的后端调用 /api/provisioning/* 端点，使用该密钥创建推理密钥（前缀 sk-syn-).
每个推理密钥的作用范围限定于同一个 workspace，并可附带 USD 消费上限和不透明的 metadata 标签。
将推理密钥交付给你的客户。可随时单独撤销其中任意一个——删除 provisioning key 不会影响它已经创建的推理密钥。

ℹ

provisioning key 本身只能在 Console 中创建——没有用于生成 provisioning key 的 API。打开 Console → Provisioning Keys （仅限 owner / admin）。

认证

将 provisioning key 作为 Bearer token 传递。它适用于仅于 /api/provisioning/* ——provisioning key 无法发起推理调用，普通的 inference key 也无法调用这些管理端点（两种情况都会返回 401 wrong_key_kind).

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

创建推理密钥

POST /api/provisioning/keys

参数	类型	说明
`name`	`string`	密钥的可读标签（例如 "Device abc-123"）。
`quota`	`number`	以 USD 计的消费上限。省略或设为 0 表示无限制。
`allowed_models`	`string`	以逗号分隔的模型允许列表（例如 "claude-haiku-4-5"）。留空 = 该 workspace 可访问的所有模型。
`ip_whitelist`	`string`	以逗号分隔的 IP / CIDR 允许列表，适用于使用此密钥发起的请求。留空 = 无限制。
`expires_at`	`string`	可选的 RFC3339 过期时间戳。省略则不过期。
`include_byok_in_limit`	`boolean`	若为 true，BYOK 调用将按上游标价计入此密钥的配额。默认为 false。
`metadata`	`object`	你自定义的不透明 JSON 标签（例如 {"tenant_id":"acme"}）。原样存储，最大 8KB。仅用于列出 / 过滤——绝不影响鉴权。

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 中读取，它出现在列表 / 检索响应里。

✓

在创建时为密钥打上 metadata （租户、设备、环境），以便日后能按过滤条件列出、审计和批量撤销它们。以这种方式创建的密钥也会出现在 Console → API Keys 并带有 Programmatic 来源徽章及其标签。

为每个密钥设定美元上限?LLM API cost calculator 能把客户的预期 token 用量换算成每月支出金额,你可以把它设为 quota。