API Keys & Provisioning

plm_ API 키를 발급·관리하고, 자동화를 위한 관리 키로 자식 키를 프로비저닝합니다.

이 페이지의 엔드포인트는 대시보드 관리용으로, 로그인 세션의 JWT 액세스 토큰(Authorization: Bearer <JWT access token>)으로 인증합니다. plm_ 키나 SDK 호환 토큰으로는 호출할 수 없습니다. 여기서 발급한 plm_ 키가 곧 OpenAI · Anthropic SDK 호출에 사용하는 키입니다.

개인 키#

GET/v1/keys

GET/v1/keys/usage

POST/v1/keys

PATCH/v1/keys/{id}

DELETE/v1/keys/{id}

POST /v1/keys로 새 키를 발급합니다. 본문 필드는 모두 선택이며, 생략하면 기본값이 적용됩니다.

파라미터	타입	필수	설명
name	string \| null	선택	키 이름. 생략하면 `"Default"`.
allowed_models	string[] \| null	선택	이 키로 호출 가능한 모델 ID 화이트리스트. 비우거나 `null`이면 모든 모델 허용.
monthly_budget_krw	integer \| null	선택	월별 지출 상한(원). null이면 무제한.
expires_at	datetime \| null	선택	키 만료 시각(ISO 8601). null이면 만료 없음.
pii_masking_enabled	boolean	선택	아웃바운드 PII 마스킹 사용 여부. 기본값 `true`.
response_cache_mode	string	선택	`off` \| `exact` \| `semantic`. 기본값 `off`. 아래 "키 스코프" 참고.
scopes	string[] \| null	선택	권한 스코프. `"chat"` · `"usage:read"` 조합. 그 외 값은 422. 아래 "키 스코프" 참고.
ip_allowlist	string[] \| null	선택	허용 IP/CIDR 목록(예: `203.0.113.0/24`). `null`이면 제한 없음. 잘못된 형식은 422.

create key

curl https://router.pleum.ai/v1/keys \
  -H "Authorization: Bearer <JWT access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "allowed_models": ["gpt-4o", "claude-sonnet-4-6"],
    "monthly_budget_krw": 50000,
    "expires_at": "2026-12-31T23:59:59Z",
    "pii_masking_enabled": true,
    "response_cache_mode": "off",
    "scopes": ["chat"],
    "ip_allowlist": ["203.0.113.0/24"]
  }'

응답에는 키 메타데이터와 함께 key(전체 비밀키)가 포함됩니다. 전체 키는 생성 시 단 한 번만 노출되며 이후에는 key_prefix(예: plm_a1b2)만 조회됩니다. 안전한 곳에 즉시 보관하세요.

201 Created

{
  "id": "k_a1b2c3d4",
  "name": "production",
  "key_prefix": "plm_a1b2",
  "key": "plm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "allowed_models": ["gpt-4o", "claude-sonnet-4-6"],
  "monthly_budget_krw": 50000,
  "is_active": true,
  "pii_masking_enabled": true,
  "response_cache_mode": "off",
  "scopes": ["chat"],
  "ip_allowlist": ["203.0.113.0/24"],
  "created_at": "2026-06-27T09:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z"
}

금융 · 의료 · 공공 등 규제 산업 계정은 pii_masking_enabled=false로 키를 생성하거나 마스킹을 끌 수 없습니다 — 시도하면 403이 반환됩니다.

키 스코프#

scopes는 키가 어떤 API를 호출할 수 있는지를 제한합니다. "chat"은 모델 호출(과금되는 호출)을, "usage:read"는 read-only 사용량 리포트 (GET /v1/usage/report)를 허용합니다. null(기본)은 레거시 동작으로 모델 호출만 가능합니다. scopes를 지정했는데 "chat"이 없으면 과금 호출이 403으로 거부됩니다 — 지출 권한 없는 모니터링 전용 키를 만들 수 있습니다.

파라미터	타입	필수	설명
scopes	string[] \| null	선택	`["chat"]` · `["usage:read"]` · 둘 다. `null` = 레거시(모델 호출 전용).
ip_allowlist	string[] \| null	선택	키 사용을 이 IP/CIDR 대역으로 한정. 모든 키 인증 지점에서 강제되며, `null`이면 제한 없음.
response_cache_mode	string	선택	`off`(기본) \| `exact`(동일 요청 정확 매치) \| `semantic`(정확 매치 + 임베딩 유사도). 캐시 적중 시 프로바이더 호출 없이 응답하며 과금은 0, 응답에 `"cached": true`가 표시됩니다.

관리 키와 프로비저닝#

GET/v1/management-keys

POST/v1/management-keys

DELETE/v1/management-keys/{id}

POST /v1/management-keys로 plmk_ 관리 키를 발급할 수 있습니다(본문 {name}). 관리 키는 자식 키를 프로비저닝하는 데 쓰이며, 전체 키는 생성 시 한 번만 노출됩니다. GET · POST(201) · DELETE를 지원합니다.

GET/v1/provisioning/keys

POST/v1/provisioning/keys

DELETE/v1/provisioning/keys/{id}

프로비저닝 엔드포인트(/v1/provisioning/keys)는 JWT가 아니라 plmk_ 관리 키로 인증합니다 (Authorization: Bearer plmk_...). 대시보드 세션 없이 키를 발급해야 하는 CI · 자동화에 적합합니다. GET(소유자의 키 목록) · POST(201, 자식 키 생성) · DELETE를 지원합니다.

provision child key

curl https://router.pleum.ai/v1/provisioning/keys \
  -H "Authorization: Bearer plmk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-runner",
    "monthly_budget_krw": 20000
  }'

프로비저닝으로 만든 자식 키 본문(ProvisionKeyCreate)에는 name과 monthly_budget_krw만 지정할 수 있습니다 — allowed_models · pii_masking_enabled · expires_at는 설정할 수 없습니다.