인증 및 범위
Kaleidr 플랫폼 API를 호출할 때마다 자격 증명 하나를 포함해야 합니다. 자격 증명은 세 가지이며 API는 유형에 따라 다르게 처리합니다.
- 게시 가능 키는 브라우저에서 조직을 식별합니다. 이 키만으로 API를 호출할 수 없으며 세션으로 교환해야 합니다.
- 세션 토큰은 브라우저가 실제로 API를 호출할 때 사용하는 자격 증명입니다. 유효 기간이 짧으며 하나의 웹사이트 출처와 하나의 제품에 연결됩니다.
- 서버 키는 백엔드가 각 요청마다 직접 전송하는 비밀 자격 증명입니다.
이 페이지에서는 각 자격 증명의 전송 방식, 세션 교환 과정, 범위가 허용하는 작업, vendor 범위의 부여 방식, 각 인증 오류의 원인과 해결 방법을 설명합니다. 자격 증명이 유출되었을 때 가능한 작업은 보안 모델을 참조하세요.
자격 증명 유형
| 자격 증명 | 접두사 | 보관 위치 | 사용 방식 | 요금제 |
|---|---|---|---|---|
| 게시 가능 키 | kld_pk_live_… | 페이지 소스 | 세션 교환에 한 번 전송하며 다른 모든 엔드포인트에서는 거부됨 | Free, Pro, Enterprise |
| 세션 토큰 | kld_sess_live_… | 브라우저 메모리 | 발급된 페이지에서 실행하는 모든 런타임 호출에 전송됨 | 게시 가능 키 또는 게시된 지도에서 발급 |
| 서버 키 | kld_sk_live_… | 백엔드에만 보관 | 모든 런타임 호출에 전송되며 요청에 Origin 헤더가 있으면 거부됨 | Pro, Enterprise |
| 레거시 키 | kld_live_… | 백엔드 | 서버 키처럼 직접 자격 증명으로 사용 가능. 교체하면 서버 키가 발급됨 | 기존 키만 해당 |
키 관리 API에서 environment: "test"로 생성한 키는 live 대신 test를 사용합니다(kld_pk_test_…, kld_sk_test_…). 테스트 키로는 기본 지도 타일을 불러올 수 없습니다.
키 전체 값은 생성 또는 교체할 때 단 한 번 표시됩니다. Kaleidr는 해시만 저장하므로 분실한 키는 복구할 수 없습니다. 키를 교체하세요.
자격 증명 전송
두 헤더 중 어느 쪽에든 자격 증명을 전송할 수 있습니다. 모든 엔드포인트가 두 헤더를 모두 허용합니다.
Authorization: Bearer kld_sk_live_…
X-Api-Key: kld_sk_live_…
요청에 두 헤더가 모두 있으면, Authorization 값이 Kaleidr 접두사로 시작할 때 이를 사용하고 그렇지 않으면 X-Api-Key를 읽습니다. 서버 키를 URL에 넣지 마세요.
세션 교환을 제외한 런타임 엔드포인트에서 각 자격 증명이 허용하는 작업은 다음과 같습니다.
| 자격 증명 | 런타임 엔드포인트의 결과 |
|---|---|
| 게시 가능 키 | 401 publishable_requires_session. 먼저 세션으로 교환해야 합니다. |
Origin 헤더가 없는 서버 키 | 허용된 뒤 IP 허용 목록, 범위, 허용 제품, 할당량 및 요청 속도 제한을 검사합니다. |
Origin 헤더가 있는 서버 키 | 403 server_key_in_browser. 브라우저는 교차 출처 요청에 Origin을 추가하므로 API는 웹페이지에서 사용된 서버 키를 식별할 수 있습니다. |
| 발급된 출처에서 사용한 세션 토큰 | 허용됩니다. |
다른 Origin에서 사용한 세션 토큰 | 403 session_origin_mismatch. |
Origin 없이 사용한 게시된 지도 세션 토큰 | 403 session_origin_mismatch. |
JavaScript SDK는 동일한 규칙을 더 일찍 적용합니다. Kaleidr.mount는 브라우저에서 kld_sk_… 키를 발견하면 요청을 전송하지 않고 거부합니다.
세 션 교환
게시 가능 키는 하나의 엔드포인트에서 세션 토큰으로 교환됩니다. SDK는 키를 사용한 마운트마다 이를 자동으로 수행하고 토큰을 갱신합니다. 브라우저 클라이언트를 직접 만드는 경우에만 해당 엔드포인트를 직접 호출하면 됩니다.
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
X-Api-Key: kld_pk_live_…
Content-Type: application/json
{ "product": "chat" }
product는 필수이며 chat, editor, viewer, tile 중 하나여야 합니다. 요청에 Origin 헤더가 있어야 하며 브라우저가 자동으로 추가합니다.
{
"session_token": "kld_sess_live_eyJhbGciOi…",
"expires_in": 900,
"product": "chat",
"basemap_style_id": null
}
| 필드 | 의미 |
|---|---|
session_token | 런타임 호출에 쓰는 자격 증명. 형식은 kld_sess_{env}_{token}입니다. |
expires_in | 유효 기간(초). 키 기반 세션은 900초 동안 유효합니다. 숫자를 하드코딩하지 말고 이 필드를 읽으세요. |
product | 세션이 연결되는 제품입니다. |
basemap_style_id | 조직의 기본 지도 스타일이며 설정하지 않았다면 null입니다. |
세션이 연결되는 대상
- 하나의 출처. 교환 요청의
Origin입니다. 다른 출처에서 호출하면 거부됩니다. - 하나의 제품.
tile세션은 채팅 엔드포인트를 호출할 수 없습니다. - 제한된 범위 집합. 세션에는 제품에 필요한 범위만 포함됩니다. 채팅은
ai, 편집기는design, 타일은maps, 뷰어는 범위가 없습니다. 키에vendor가 있고 요금제(Enterprise)가 이를 허용할 때만 채팅 세션에도vendor가 포함됩니다. 다른 제품의 세션에는 해당 범위가 포함되지 않습니다.
갱신
클라이언트는 더 긴 유효 기간을 요청할 수 없습니다. expires_in이 만료 되기 전에 다시 교환하세요. SDK는 만료 90초 전에 갱신하며, 백그라운드 탭이 다시 표시될 때 만료까지 90초 이하로 남았거나 이미 만료되었으면 갱신합니다. 갱신에 실패하면 30초마다 재시도합니다. 최초 교환에 실패하면 마운트가 실패하고 다시 시도하지 않습니다.
product: "tile"에 대한 세션 교환마다 조직의 지도 로드 한도에서 1회가 차감됩니다. 다른 제품의 세션 교환은 무료입니다. 교환에는 런타임 호출과 별도의 키별 요청 속도 제한이 적용됩니다. 할당량 및 요청 속도 제한을 참조하세요.
검사 순서
첫 번째로 실패한 검사에서 세션 교환이 중단됩니다.
| 순서 | 검사 | 실패 |
|---|---|---|
| 1 | 키가 유효함 | 401 Invalid or missing API key |
| 2 | 키의 세션 교환 속도 제한 | 429 rate_limited |
| 3 | 게시 가능 키임 | 403 publishable_key_required |
| 4 | 요청에 Origin 헤더가 있음 | 403 origin_required |
| 5 | 허용 출처 목록이 있으면 요청 출처가 포함됨 | 403 origin_not_allowed |
| 6 | 키의 제품 제한에서 해당 제품을 제외하지 않음 | 403 product_not_allowed |
| 7 | 현재 요금제에 해당 제품이 포함됨 | 403 tier_capability_not_allowed |
| 8 | 키에 제품이 요구하는 범위가 있음 | 403 insufficient_scope 또는 키에는 범위가 있지만 현재 요금제에서 허용하지 않으면 tier_capability_not_allowed |
| 9 | tile의 경우 지도 로드 횟수가 남아 있음 | 429 map_load_quota_exceeded |
터미널에서 시험하기
curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "X-Api-Key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "Content-Type: application/json" \
-d '{"product":"chat"}'
Origin은 브라우저가 아닌 클라이언트도 설정할 수 있는 일반적인 헤더이므로 이 방법이 가능합니다. 따라서 허용 출처 목록은 비밀 보관 수단이 아니라 브라우저 제어 수단으로 설명됩니다. CORS 및 허용 출처를 참조하세요.
게시된 지도의 세션
Studio에서 게시한 지도의 Kaleidr AI 타일에서 Control Tower 또는 Popup Window를 켜면 페이지에 키를 넣지 않고도 방문자에게 채팅을 제공할 수 있습니다. 페이지는 대신 지도의 공개 ID와 여는 기능을 세션으로 교환합니다.
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions
Content-Type: application/json
{ "share_id": "your-map-id", "feature": "control_tower" }
{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }
이 세션은 채팅 전용이며 ai 범위를 가지고 300초 동안 유효하고 사용량은 지도 소유자 조직에 청구됩니다. vendor는 절대 포함되지 않습니다. 요청한 페이지에서만 사용할 수 있으며 Origin이 없거나 다른 출처의 호출은 거부됩니다. 거부 조건은 다음과 같습니다.
| 상태 | 코드 | 원인 |
|---|---|---|
| 403 | origin_required | 요청에 Origin 헤더가 없습니다. |
| 404 | not_found | 해당 ID의 게시된 지도나 공유 링크가 없거나, 공유 링크의 지도가 게시 취소되었습니다. |
| 403 | chat_disabled | 지도의 Kaleidr AI가 요청한 기능을 켜지 않았습니다. |
| 403 | origin_not_allowed | 페이지가 지도에서 허 용한 도메인에 속하지 않습니다. |
| 403 | owner_has_no_organization | 지도 소유자에게 청구할 조직이 없습니다. |
| 403 | tier_capability_not_allowed | 소유자의 요금제에 채팅이 포함되지 않습니다. |
| 429 | rate_limited | 해당 지도 또는 주소에서 세션 교환을 너무 많이 요청했습니다. |
설정 방법은 게시된 지도의 Kaleidr AI를 참조하세요.
범위
키에는 범위가 포함됩니다. 엔드포인트 그룹마다 필요한 범위가 있습니다.
| 범위 | 허용 기능 | 필요 대상 |
|---|---|---|
ai | /chat/*, /retrieval/* 엔드포인트 | 채팅 및 채팅·조회 엔드포인트를 호출하는 백엔드 |
design | /design/* 엔드포인트 | Editor 세션 및 디자인 엔드포인트를 호출하는 백엔드 |
maps | 기본 지도 세션 | Tile |
vendor | 그 자체로 엔드포인트를 열지는 않지만 채팅 답변에 조직에서 게시한 데이터를 사용할 수 있습니다. | 데이터를 업로드한 경우의 채팅 |
다르게 지정하지 않으면 새 키에 ai, maps, design이 부여됩니다. Free 요금제에서는 요청에 어떤 제품을 지정하든 키에 Free 전체 기능, 즉 이 세 가지 범위와 네 제품(chat, editor, viewer, tile)이 항상 포함됩니다. vendor는 기본값이 아니며 Enterprise 조직만 해당 범위를 포함하는 키를 만들 수 있습니다.
요금제가 허용하지 않는 범위나 제품을 지정해 키를 만들면 403 tier_capability_not_allowed로 거부됩니다. 오류 없이 요청 항목을 조용히 삭제하지 않습니다. 대표적인 경우는 Free 또는 Pro에서 vendor를 요청하는 것입니다.
범위는 키 생성 시 확정됩니다. 이후에는 어떤 엔드포인트나 설정으로도 수정할 수 없습니다. 교체한 키는 기존 범위를 물려받되 현재 요금제가 더 이상 허용하지 않는 범위는 제외됩니다. 변경하려면 새 키를 생성하고 기존 키를 취소하세요.
Free에서 키 교체에는 Free 규칙이 적용됩니다. Free 요금제에서 게시 가능 키를 교체하면 기존 키와 무관하게 교체 키에 Free의 모든 기능(ai, maps, design 및 네 제품)이 부여됩니다. Free에서는 서버 키나 레거시 키를 교체할 수 없으며 403 free_plan_publishable_only가 반환됩니다.
키의 사용 가능 범위는 키와 요금제 중 더 제한적인 쪽에 따릅니다
각 요청은 키에 저장된 범위와 제품을 조직의 현재 요금제에서 제공하는 기능과 대조합니다. 요금제 변경이 키 자체를 수정하지는 않지만 키가 수행할 수 있는 작업은 바뀝니다.
insufficient_scope: 키에 해당 범위가 처음부터 부여되지 않았습니다. 해결: 범위가 있는 키를 사용합니다.tier_capability_not_allowed: 키에는 해당 범위가 있으나 현재 요금제가 지원하지 않습니다. 해결: 요금제를 변경합니다.
vendor는 엔드포인트를 열지 않으므로 두 번째 규칙의 예외입니다. Enterprise 미만 요금제에서 vendor를 저장한 키도 거부되지 않으며 요청은 성공하지만, 답변은 조직 데이터를 사용하지 않고 생성됩니다.
제품 목록이 비어 있는 키는 요금제에 포함된 모든 제품에 접근할 수 있습니다. 범위가 없는 키는 모든 곳에서 거부됩니다.
제품 제한은 모든 키에 적용됩니다
allowed_products는 키가 사용할 수 있는 제품을 chat, editor, viewer, tile 중 일부로 제한합니다. 이 제한은 키 유형에 관계없이 사용 시점에 적용됩니다.
| 키 | 제한 확인 시점 | 거부 |
|---|---|---|
| 게시 가능 키 | 세션 교환 시 요청한 product 확인 | 403 product_not_allowed |
| 서버 키 또는 레거시 키 | 매 런타임 요청 시 엔드포인트가 속한 제품 확인 | 403 product_not_allowed |
각 엔드포인트 그룹은 필요한 범위에 해당하는 제품에 속합니다.
| 엔드포인트 | 범위 | 제한된 키에서 허용해야 하는 제품 |
|---|---|---|
/chat/*, /retrieval/* | ai | chat |
/design/* | design | editor |
예를 들어 "allowed_products": ["tile"]로 만든 서버 키는 ai 범위를 가지고 있어도 /chat/control/stream 호출 시 403 product_not_allowed로 거부됩니다. viewer만 허용하는 서버 키는 어떤 런타임 엔드포인트도 호출할 수 없습니다. 게시된 지도에는 키가 필요하지 않기 때문입니다. 키가 범위 내의 모든 엔드포인트에 접근해야 한다면 제품 목록을 비워 두세요.
세션 토큰은 교환할 때 이미 하나의 제품에 연결되었으므로 여기에서 다시 검사하지 않습니다.
| Free | Pro | Enterprise | |
|---|---|---|---|
| 게시 가능 키 | 예 | 예 | 예 |
| 서버 키 | 아니요 | 예 | 예 |
ai, maps, design | 예 | 예 | 예 |
vendor | 아니요 | 아니요 | 예 |
Pro는 Free 기능에 더해 서버 키와 더 높은 활성 키 개수 제한을 제공합니다. 전체 요금제 비교표는 API 키 발급을 참조하세요.
vendor 범위
vendor 자체는 엔드포인트를 열지 않습니다. 이 범위는 해당 키로 만 든 채팅 답변이 Kaleidr의 일반 지식과 함께 조직에서 게시한 데이터를 사용할 수 있는지를 결정합니다. 업로드부터 답변 생성까지 전체 과정은 자체 데이터 개요에 설명되어 있습니다.
이 범위를 사용할 수 있는 대상은 다음과 같습니다.
- Free 및 Pro는
vendor를 가질 수 없습니다.vendor_acknowledged전송 여부와 관계없이 해당 범위를 포함한 키 생성 요청은 403tier_capability_not_allowed로 거부되며 키가 생성되지 않습니다. - Enterprise는
vendor키를 만들 수 있습니다.
이 범위는 키를 통한 데이터 읽기에만 해당합니다. 데이터 업로드는 조직 소유자 또는 관리자에게 부여되는 별도 권한이며 어떤 키에도 속하지 않습니다. 업로드 역시 Enterprise 전용이므로 Free와 Pro에서는 비즈니스 데이터를 업로드할 수 없습니다. 로그인한 사용자가 Kaleidr Studio의 지도에 추가하는 파일은 다른 기능으로 모든 요금제에서 사용할 수 있지만 범위로 읽을 수는 없습니다. 지도 데이터세트를 참조하세요.
API Keys 페이지에서는 vendor를 부여할 수 없습니다. 키 관리 API로 키를 만드세요.
curl -s https://api.kaleidr.com/shared-api/api-keys \
-H "Authorization: Bearer $KALEIDR_ACCOUNT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "store-locator-chat",
"key_type": "publishable",
"scopes": ["ai", "vendor"],
"vendor_acknowledged": true,
"allowed_origins": ["https://www.example.com"]
}'
vendor를 포함한 게시 가능 키에는 vendor_acknowledged: true가 필요합니다. 없으면 422 vendor_scope_requires_acknowledgement로 실패합니다. 게시 가능 키는 공개된 페이지 소스에 있으므로 해당 키가 읽을 수 있는 데이터는 페이지 방문자 누구나 읽을 수 있습니다. 서버 키에는 이 확인이 필요하지 않습니다.
게시 가능 키에 vendor를 추가하기 전에 다음을 확인하세요.
- 웹사이트마다 키를 하나씩 사용하세요. 조직 데이터 기반 답변이 필요한 사이트에만
vendor를 부여하세요. - 게시한 데이터는 해당 사이트에서 공개된 것으로 취급하세요. 원가, 공개되지 않은 요금, 페이지에 게시하기 어려운 정보는 올리지 마세요.
- 이미 발급된 세션에는 새 범위가 추가되지 않습니다.
vendor를 포함해 만든 키는 그 후 교환한 세션에만 해당 범위를 부여합니다.
vendor를 철회하려면 키를 취소하고 해당 범위가 없는 새 키를 만드세요. 취소는 이미 발급된 세션을 포함해 다음 요청부터 적용됩니다.
조직이 Enterprise를 떠나는 경우
Enterprise에서 Pro 또는 Free로 변경해도 키는 수정되지 않으며 모두 작동 중지되는 것은 아닙니다.
| 대상 | 변경 후 |
|---|---|
vendor를 포함한 키 | 다른 용도로는 계속 작동합니다. 답변에서 조직 데이터가 더 이상 사용되지 않지만 오류, 상태, 필드에는 표시되지 않습니다. |
| 변경 전에 발급한 브라우저 세션 | 종료됩니다. 다음 요청에서 401을 반환하고 SDK가 vendor가 없는 새 세션을 발급받습니다. |
vendor를 포함한 키 교체 | Pro에서는 201로 성공합니다. 새 키는 vendor를 제외한 동일 범위를 가지며 제품 목록은 그대로입니다. Free에서는 게시 가능 키의 교체 키에 기존 키와 무관하게 ai, maps, design 및 네 제품이 포함됩니다. 서버 키나 레거시 키 교체는 403 free_plan_publishable_only로 거부됩니다. |
vendor를 포함한 키 생성 | 403 tier_capability_not_allowed로 거부됩니다. |
| 기존 릴리스 | 소유자와 관리자는 모든 요금제에서 업로드 API를 이용해 목록 확인, 게시 취소, 삭제가 가능합니다. Free와 Pro에서 업로드와 게시는 403 vendor_data_not_on_plan으로 거부됩니다. |
Enterprise로 돌아오면 vendor가 여전히 저장된 키는 다시 데이터에 접근할 수 있습니다. 하위 요금제에서 교체한 키에는 해당 범위가 복원되지 않으므로 새 키를 만드세요.
키 제한
| 제한 | 적용 대상 | API Keys 페이지에서 설정 | 키 관리 API에서 설정 | 거부 |
|---|---|---|---|---|
| 허용 출처 | 게시 가능 키 | 예 | 예(allowed_origins) | 교환 시 403 origin_not_allowed |
| 허용 제품 | 모든 키 | 아니요 | 예(allowed_products) | 게시 가능 키는 교환 시, 서버 및 레거시 키는 각 런타임 요청 시 403 product_not_allowed. 제품 제한 참조. |
| IP 허용 목록 | 서버 및 레거시 키 | 아니요 | 예(allowed_ips) | 403 ip_not_allowed |
| 월간 상한 | 모든 키 | 아니요 | 예(monthly_cap_tokens) | 429 quota_exceeded |
| 만료 | 모든 키 | 아니요 | 예(expires_at) | 만료 날짜 이후 401 |
| 범위 | 모든 키 | 아니요 | 생성 시에만(scopes) | 403 insufficient_scope |
허용 출처. 최대 100개 항목이며 각 항목은 경로를 제외한 scheme://host[:port] 형식입니다. 게시 가능 키에서 목록이 비어 있으면 모든 출처가 허용됩니다. 상세 조건과 실패 원인은 CORS 및 허용 출처를 참조하세요.
IP 허용 목록. 최대 100개 IP 주소 또는 CIDR 블록을 등록할 수 있습니다. 모든 주소에 일치하는 블록(/0)은 거부되므로 모든 주소를 허용하려면 목록을 비워 두세요. 목록이 있으나 호출자의 주소를 확인할 수 없는 경우도 요청이 거부됩니다.
월간 상한. 청구 기간에 이 키 하나가 조직의 AI 크레딧에서 사용할 수 있는 양의 상한입니다. 할당량 및 요청 속도 제한을 참조하세요.
이미 발급된 세션에 반영되는 변경
세션은 각 요청마다 상위 키를 다시 확인하므로 접근 권한 제거는 빠르게 적용됩니다. 접근 권한 추가에는 새 세션 교환이 필요합니다.
| 키 또는 계정 변경 | 이미 발급된 세션에 미치는 영향 |
|---|---|
| 키 취소 또는 유예 기간 없이 교체 | 다음 요청에서 401. |
| 세션 출처를 키의 허용 출처 목록에서 제거 | 다음 요청에서 401. |
| 세션 제품을 키의 허용 제품 목록에서 제거 | 다음 요청에서 401. |
| 요금제 하향 | 변경 전에 발급된 세션은 401. 변경 후 교환한 세션은 현재 요금제에 없는 기능 사용 시 403 tier_capability_not_allowed. |
| 월간 상한 추가 또는 감소 | 다음 요청부터 적용. |
| 월간 상한 제거 | 다음 세션 교환부터 적용. |
| 요금제 상향 | 다음 세션 교환부터 적용. |
세션 유효 기간이 몇 분이므로 "다음 교환부터"라고 해도 기다리는 시간은 짧습니다. SDK가 갱신하면서 코드 변경 없이 반영합니다.
키 관리 API
kaleidr.com/api-keys의 API Keys 페이지에서는 키 이름, 유형, 허용 출처를 설정할 수 있습니다. 이 페이지의 나머지 설정은 동일한 API를 통해 처리합니다.
- 기본 URL:
https://api.kaleidr.com/shared-api/api-keys - 인증: 조직의 소유자 또는 관리자인 Kaleidr 로그인 계정의 액세스 토큰을
Authorization: Bearer로 전송합니다. 이곳에서는 플랫폼 키를 사용할 수 없습니다. 현재 키 관리 전용 장기 자격 증명은 별도로 제공하지 않습니다. - 조직: 조직을 지정하지 않으면 기본 조직을 사용합니다. 다른 조직을 지정하려면 키를 생성할 때 JSON 본문에
org_id를 넣고, 다른 모든 경로에서는 쿼리 매개변수?org_id=로 전송합니다. 생성 경로의 쿼리에 있는org_id는 무시됩니다.
| 메서드 및 경로 | 목적 | 성공 |
|---|---|---|
POST / | 키 생성 | 201, 키 객체 및 plaintext_key |
GET / | 활성 키를 최신순으로 나열 | 200 |
GET /{id}/events?limit=1..200 | 키 감사 이벤트 | 200 |
PATCH /{id} | 제한 변경 | 200, 키 객체 |
POST /{id}/rotate | 키 교체 | 201, 새 키 및 plaintext_key |
POST /{id}/revoke | 키 취소 | 200, 키 객체 |
삭제 경로는 없습니다. 키를 사용 중지하려면 취소하세요.
키 생성 시 허용하는 필드는 다음과 같습니다.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
name | 1~200자 문자열 | 필수 | |
org_id | UUID | 기본 조직 | 키가 생성될 조직입니다. 본문으로 보내야 하며 이 경로의 쿼리 매개변수는 무시됩니다. |
key_type | "publishable" 또는 "server" | "publishable" | Free에서는 "server"가 403 free_plan_publishable_only로 거부됩니다. |
environment | "live" 또는 "test" | "live" | |
scopes | 문자열 배열 | ["ai", "maps", "design"] | ai, maps, design, vendor 중 선택합니다. 다른 값은 422 unknown_scope입니다. 요금제에서 지원하지 않는 범위(Enterprise 미만의 vendor)는 403 tier_capability_not_allowed입니다. |
allowed_origins | 최대 100개 문자열 배열 | [] | 게시 가능 키에서는 비어 있으면 모든 출처를 뜻합니다. |
allowed_products | 문자열 배열 | [] | chat, editor, viewer, tile 중 선택합니다. 비어 있으면 모두 허용합니다. 그 외 값은 422 unknown_product입니다. 게시 가능·서버·레거시 키 모두에 적용됩니다. 제품 제한을 참조하세요. |
allowed_ips | 최대 100개 문자열 배열 | [] | IP 주소 또는 CIDR 블록입니다. |
monthly_cap_tokens | 0 이상의 정수 | 없음 | 1 이상이면 상한을 설정합니다. 0 또는 null은 상한 없음입니다. |
expires_at | 미래 날짜 및 시간 | 없음 | |
vendor_acknowledged | 불리언 | false | vendor가 있는 게시 가능 키에 필수(Enterprise)입니다. |
PATCH는 name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens, expires_at을 허용합니다. 변경할 필드만 보내세요. 명시적으로 null을 보내면 값을 지웁니다. scopes는 허용하지 않습니다.
rotate는 { "grace_hours": 0 }을 허용하며 범위는 0~8760입니다. 교체 키는 기존 키의 범위를 상속하지만 현재 요금제가 지원하지 않는 범위는 제외됩니다. Free에서는 교체 키에 항상 Free 전체 기능이 포함되며 서버 또는 레거시 키는 교체할 수 없습니다(403 free_plan_publishable_only). 값이 0이면 기존 키와 세션은 즉시 중단됩니다. 유예 기간을 지정하면 종료 시점까지 기존 키를 사용할 수 있고 활성 키 수 한도에 계속 포함되며 다시 교체할 수 없습니다. API Keys 페이지는 24시간 유예 기간을 사용합니다.
이 경로의 오류는 오류: 키 관리를 참조하세요.
인증 오류
401은 API가 자격 증명 자체를 허용하지 않음을 뜻합니다. 403은 자격 증명을 인식하지만 요청을 거부함을 뜻합니다. 모두 {"detail": "<code>"} 형식입니다.
브라우저에서는 자격 증명이나 출처가 거부되면 응답에 CORS 헤더가 없으므로 본문 대신 CORS 오류가 표시됩니다. 범위나 요금제 검사에서 나중에 거부된 요청은 응답을 읽을 수 있으며 SDK는 kaleidr session exchange failed (403)이라고 보고합니다. 두 경우 모두 개발자 도구의 Network 탭에서 요청을 열어 코드를 확인하세요. CORS 및 허용 출처를 참조하세요.
| 상태 | 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| 401 | Invalid or missing API key | 자격 증명 누락, 알 수 없거나 취소·만료된 키, 만료된 세션, 상위 키가 취소되거나 출처·제품 허용이 제거된 세션, 요금제 하향 전에 발급된 세션, 조직이 일시 중지되었거나 요금제가 없음. | API Keys 페이지에서 키 값과 상태를 확인합니다. 세션은 다시 교환하세요. |
| 401 | publishable_requires_session | 게시 가능 키를 런타임 엔드포인트에 전송했습니다. | 세션으로 교환하거나 서버 키로 백엔드에서 호출합니다. |
| 403 | publishable_key_required | 서버 또는 레거시 키로 세션 교환을 호출했습니다. | 교환에 kld_pk_… 키를 사용합니다. |
| 403 | origin_required | 세션 교환에 Origin 헤더가 없습니다. | 브라우저 페이지에서 호출합니다. |
| 403 | origin_not_allowed | 페이지 출처가 키의 허용 출처 또는 게시된 지도의 허용 도메인에 없습니다. | 정확한 출처를 키에, 또는 도메인을 지도에 추가합니다. |
| 403 | product_not_allowed | 키의 허용 제품에서 이 제품이 제외되었습니다. 세션 교환 시 지정한 product, 또는 서버·레거시 키가 호출한 엔드포인트의 제품입니다. | allowed_products를 변경하거나 다른 키를 사용합니다. |
| 403 | insufficient_scope | 키 생성 시 엔드포인트나 제품에 필요한 범위가 부여되지 않았습니다. | 해당 범위가 있는 키를 사용합니다. 범위는 수정할 수 없습니다. |
| 403 | tier_capability_not_allowed | 키에는 범위 또는 제품이 있으나 현재 요금제에 포함되지 않습니다. | kaleidr.com/billing에서 요금제를 변경합니다. |
| 403 | server_key_in_browser | 서버 키가 Origin 헤더와 함께 전송되었습니다. | 백엔드로 호출을 옮깁니다. 페이지 소스에 노출되었다면 키를 교체합니다. |
| 403 | session_origin_mismatch | 세션 토큰을 발급받은 출처와 다른 출처에서 사용했거나, 게시된 지도 세션을 Origin 없이 사용했습니다. | 해당 세션을 사용할 페이지에서 다시 교환합니다. |
| 403 | ip_not_allowed | IP 허용 목록을 사용하는 서버·레거시 키를 목록 밖 주소에서 사용했습니다. | 허용된 주소에서 호출하거나 allowed_ips를 변경합니다. |
| 403 | chat_disabled | 게시된 지도 교환: 지도의 Kaleidr AI가 요청한 기능을 켜지 않았습니다. | Studio에서 지도의 Kaleidr AI 타일에 있는 Control Tower 또는 Popup Window를 켭니다. |
| 403 | owner_has_no_organization | 게시된 지도 교환: 지도 소유자에게 조직이 없습니다. | 소유자가 조직을 만들거나 가입해야 합니다. |
| 404 | not_found | 게시된 지도 교환: 해당 ID의 게시된 지도나 공유 링크가 없습니다. | ID와 지도의 게시 상태를 확인합니다. |
429 및 5xx 응답을 포함한 전체 목록은 오류를 참조하세요.
관련 문서
- 보안 모델: 자격 증명 유출 시 가능한 작업.
- CORS 및 허용 출처: 허용 출처 목록 적용 방식.
- 엔드포인트: 각 범위로 호출할 수 있는 기능.
- API 키 발급: API Keys 페이지에서 키 만드는 방법.