API 키 받기
Kaleidr는 AI, 지도, 디자인을 위한 하나의 플랫폼, 하나의 SDK, 하나의 접근 시스템이며 기능 범위로 제어됩니다. 키는 실행 위치에 따라 두 가지 안전한 형태로 제공되며, 둘 다 같은 조직에 속하고 동일한 할당량에서 사용량이 차감됩니다.
| 형태 | 접두사 | 실행 위치 | 기능 |
|---|---|---|---|
| Publishable (브라우저) | kld_pk_live_… | HTML, SDK, <kaleidr-map> | origin에 제한되며 페이지 소스에 노출되어도 안전합니다. SDK가 런타임에 이를 단기 세션으로 교환합니다. server bearer로 사용할 수 없으며 키 관리도 할 수 없습니다. |
| Server ( 백엔드) | kld_sk_live_… | 서버에서만 | 서버 간 호출을 위한 완전한 bearer입니다. 선택적 IP allowlist, 제한, 만료 설정을 지원합니다. 브라우저에서는 차단됩니다(403 server_key_in_browser). |
기존 레거시 kld_live_… 키는 변경 없이 계속 인증됩니다.
각 플랜에서 허용되는 항목
이 표는 공식 플랜 → 범위 × 제품 정책입니다. 이 표는
@kaleidr/shared-types의 B2B_TIER_API_CAPABILITIES와 동일하게 유지됩니다 — 이는
키 생성 시 shared-api가 읽고 세션 교환 시 inference-api가 읽는
동일한 상수입니다. CI drift guard를 통해 이 문서의 내용이 플랫폼에서 실제로
허용되는 내용과 조용히 불일치하는 것을 방지합니다.
| 플랜 | Publishable | Server | 허용 범위 | 허용 제품 |
|---|---|---|---|---|
| Free | 예 | — (403 free_plan_publishable_only) | maps | tile |
| Pro | 예 | 예 | ai, maps, design, vendor* | chat, editor, viewer, tile |
| Enterprise | 예 | 예 | ai, maps, design, vendor* | chat, editor, viewer, tile |
* vendor는 키마다 명시 적 확인이 필요합니다(그렇지 않으면 403
vendor_scope_requires_acknowledgement).
Viewer에는 키가 전혀 필요하지 않습니다 — share id 자체가 인증 수단입니다. Free를 포함한 모든 플랜에서
키 없이 Viewer를 임베드할 수 있습니다. Viewer 임베드에 키를 전달하면
product_not_allowed로 거부됩니다.
실제 허용 범위는 저장된 키 × 현재 플랜으로 결정됩니다. Pro 키가
Free로 다운그레이드되면 서버는 Free 형태의 세션으로 교환합니다 —
maps 범위와 tile 제품만 허용됩니다. Free 키를 다시 확장하려면
기존 키를 수정하는 것이 아니라 상위 플랜에서 새 키를 생성해야 합니다(
Errors — Key management 참조).
테스트 키
두 형태 모두 test 버전을 제공합니다 (kld_pk_test_…, kld_sk_test_…).
테스트 키는 sandbox가 아닙니다. 동일한 API에 인증하고, 동일한 모델을 호출하며, live 키와 동일한 월간 사용량 한도를 차감합니다. 차이는 두 가지입니다:
- test publishable 키는 origin allowlist 없이 생성할 수 있지만 live 키는 그렇게 할 수 없습니다;
- test 키는 basemap tile을 제공할 수 없습니다.
테스트 키는 staging 트래픽을 구분하고 별도로 취소할 수 있도록 사용하는 것이 실제 가치입니다. 무료 키처럼 사용하지 마세요.
키 생성
- 로그인한 뒤 계정의 API Keys를 엽니다 (kaleidr.com/api-keys) — 조직 관리자 만 사용할 수 있습니다.
- 키 생성 — 이름을 지정하고 Browser (publishable) 또는
Server를 선택합니다. Pro 및 Enterprise에서는 해당 플랜의 전체 권한
(
ai,maps,designscopes;chat,editor,viewer,tileproducts)으로 생성됩니다. Free에서는maps/tile로 제한된 Browser 키이며 Server 옵션은 제공되지 않습니다. - live Browser 키는 최소 하나의 allowed origin에 제한되어야 합니다 — origin이 없는 live publishable 키는 페이지 소스에 상시 비밀 값이 남게 되므로 거부됩니다.
kld_pk_live_…/kld_sk_live_…값을 한 번만 복사하세요 — 한 번만 표시되고 다시 표시되지 않습니다.
모든 임베드에 필요한 두 가지 전제 조건
현재 두 항목 모두 제품 페이지에는 문서화되어 있지 않으며 각각 독립적으로 첫 번째 통합을 막을 수 있습니다.
1. Origin allowlist
세션 교환은 브라우저의 Origin 헤더를 키의 allowlist와 비교합니다.
일치하지 않으면 403 session_origin_mismatch로 거부됩니다. file://은
Origin을 전혀 보내지 않습니다 — 복사한 스니펫을 처음 테스트할 때 흔히 사용하는 방식이지만 —
키를 사용하는 모든 임베드는 HTTP(S)로 제공해야 합니다.
기존 키의 allowlist는 플랫폼 키 자체가 아니라 Cognito org-admin JWT를 사용해 업데이트하세요:
PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json
{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }
PATCH는 키의 snapshot cache를 즉시 무효화하며, origin을 제거하면
이미 해당 origin에 연결된 세션도 종료됩니다 — 모든 세션 요청은
키의 현재 allowed_origins에 대해 origin을 다시 확인하므로 제거된 origin에서 오는
다음 요청은 TTL이 끝날 때까지 기다리지 않고 즉시 거부됩니다.
origin을 추가하면 반대로 새 세션이 허용되지만 기존 세션에는
소급 적용되지 않습니다.
2. 고객 CSP
페이지의 Content Security Policy는 각 제품이 로드하는 리소스를 허용해야 합니다.
제품별 설정은 Content Security Policy를
참조하세요 — Tile과 Viewer는 SDK loader와 하나의 frame host만 추가합니다.
Chat과 Editor는 MapLibre가 부모 문서에서 실행되기 때문에 'wasm-unsafe-eval'과
지도 공급자 host도 필요합니다.
사용 방법
브라우저에서는 publishable 키를 전달하면 SDK가 이를 단기 세션으로 교환합니다:
<kaleidr-map product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="height:480px"></kaleidr-map>
서버에서는 server 키를 bearer로 전송합니다:
Authorization: Bearer kld_sk_live_…
키는 사용자의 조직으로 인증됩니다. 사용량은 조직의 월간 할당량에서 차감됩니다. 각 범위가 허용하는 기능은 Auth & scopes를, 모든 세션 교환을 제어하는 브라우저 origin allowlist는 CORS & allowed origins를 참조하세요.