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를 삭제해도 않습니다 이미 생성한 추론 키에 영향을 주지

인증

프로비저닝 키를 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 에서 읽을 수 있으며, 목록/조회 응답에 포함됩니다.

키별 USD 상한을 정하시나요? LLM API cost calculator는 고객의 예상 토큰 사용량을 월간 지출 금액으로 환산해 주며, 이 값을 quota 로 설정할 수 있습니다.