管理密钥

管理密钥让你用自己的代码管理工作区：为客户或设备创建推理密钥并设定上限，读取用量、日志和设置。它不能调用模型。

创建管理密钥

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 里。下面是管理密钥和密钥接口特有的错误码。

Provisioning 密钥和 /api/provisioning

管理密钥推出之前签发的密钥（sk-syn-prov-）继续可用，带 keys.read 和 keys.write 两个权限范围。旧路径 /api/provisioning/keys 仍然可用，字段名保持原样（quota、status）。新的集成请用 /api/v1/keys。

管理 API 还涵盖账单、请求日志、提示词和工作区设置，详见 API 概览和 OpenAPI 文档。