관리 키

관리 키는 코드에서 워크스페이스를 관리할 때 쓰는 키입니다. 고객이나 기기가 사용할 추론 키를 만들고 한도를 걸 수 있으며, 사용량과 로그, 설정을 읽을 수 있습니다. 모델은 호출할 수 없습니다.

관리 키 만들기

1. 콘솔에서 API 키 › 관리 키를 열고 관리 키 만들기를 선택합니다. 관리자와 워크스페이스 소유자만 만들 수 있습니다.
2. 키의 소유자와 스코프를 선택합니다.
3. 키를 복사합니다. 키는 sk-syn-admin-으로 시작하며 한 번만 표시됩니다.

스코프

스코프 하나는 관리 API의 한 영역을 엽니다. 쓰기 스코프에는 같은 영역의 읽기 스코프가 포함됩니다. 키에 없는 스코프가 필요한 요청은 403 insufficient_scope를 반환합니다.

키의 소유자

• 나. 워크스페이스를 나가면 키가 비활성화됩니다. 워크스페이스에 남아 있더라도 관리자 권한을 잃으면 요청이 403 key_creator_not_authorized를 반환합니다.
• 워크스페이스. 만든 사람이 나가거나 역할이 바뀌어도 키는 계속 동작합니다. CI와 각종 연동에는 이쪽을 쓰세요. 만든 사람이 나가면 이 키와 이 키로 만든 추론 키가 워크스페이스 소유자에게 넘어가며, 모두 계속 동작합니다.

소유자는 키를 만들 때 정하며, 나중에 바꿀 수 없습니다.

인증

키는 Bearer 토큰으로 보냅니다. 관리 키는 관리 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>로 메타데이터의 어떤 필드로든 필터링할 수 있습니다. 결과는 페이지 단위로 나오며, 다음 페이지는 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 비용 계산기 페이지에서 고객의 예상 토큰 사용량을 월 비용으로 환산해 보세요. 그 금액을 limit_usd로 설정하면 됩니다.

오류

오류는 관리 API의 공통 형식으로 반환됩니다. error.code는 원인을, error.message는 해결 방법을 알려 줍니다. /api/provisioning/keys에서는 같은 코드가 error.type에 담깁니다. 관리 키와 키 API에서 나오는 코드는 다음과 같습니다.

프로비저닝 키와 /api/provisioning

관리 키가 나오기 전에 발급된 키(sk-syn-prov-)는 keys.read, keys.write 스코프를 가진 채로 계속 동작합니다. 이전 주소인 /api/provisioning/keys도 기존 필드 이름(quota, status) 그대로 계속 제공됩니다. 새로 연동할 때는 /api/v1/keys를 사용하세요.

관리 API는 결제, 요청 로그, 프롬프트, 워크스페이스 설정도 다룹니다. API 개요와 OpenAPI 문서를 참고하세요.