본문으로 건너뛰기

CORS 및 허용된 origin

Publishable key(kld_pk_live_…)는 allowed-origins list를 가집니다 — key 사용이 허용된 browser origin입니다. key를 mint할 때 설정하세요(예: https://acme.com, https://app.acme.com). live publishable key에는 최소 하나가 필요합니다. Server key(kld_sk_live_…)에는 CORS grant가 없으므로 page가 그 key로 생성된 response를 읽을 수 없습니다. 다만 무엇을 막는지 구분해야 합니다. CORS는 response를 차단하지 request를 막는 것이 아닙니다 — page source에 server key를 넣은 순간 이미 노출됩니다. 따라서 SDK는 mount 시 kld_sk_…를 거부합니다. server key는 server-to-server 전용입니다.

적용 방식​

  • **Preflight (OPTIONS)**는 permissive합니다 — requested origin을 반영하여 browser가 계속 진행할 수 있게 합니다(preflight에는 key가 전달되지 않음).
  • 실제 request는 request Origin이 key의 allowed list에 있을 때만 Access-Control-Allow-Origin header를 받습니다. allowlist에 없는 origin은 ACAO header가 없으므로 browser가 response를 차단합니다.

Cookie는 사용하지 않습니다 — platform API는 bearer-token auth이므로 Access-Control-Allow-Credentials가 없습니다.

Publishable key는 URL을 통해 tile CDN으로 이동​

tile.kaleidr.com은 publishable key를 ?key= query parameter로 받습니다. 의도된 설계이며 중요한 결과가 있습니다. query string은 CDN access log, browser history, 중간 proxy에 기록됩니다.

이는 publishable key가 설계상 public이기 때문에 허용됩니다 — 이미 page source에 포함됩니다. 안전성을 확보하는 것은 key별 origin allowlist이며, edge가 모든 tile request에 이를 적용하고 key가 maps scope로 제한되어 있기 때문입니다.

server key에는 허용되지 않습니다. 절대로 kld_sk_…를 URL에 넣지 마세요. 유출된 server key는 API가 거부하는 시점에 이미 노출된 상태입니다.

그 외 모든 곳 — SDK session exchange, platform API — 에서는 key가 header로 이동하며 query parameter로 전달되지 않습니다.

팁​

  • bare origin(scheme://host[:port])을 사용하세요 — path 및 trailing slash 없이 — browser Origin header와 정확히 일치해야 합니다.
  • https가 필요하지만 localhost / 127.0.0.1(local testing)은 예외입니다.
  • server key를 사용하는 server-to-server call(browser Origin 없음)은 CORS-gated가 아니지만 일반적인 auth + scope check는 그대로 적용됩니다.
  • Server key는 optional IP allowlist도 지원합니다 — list 외 IP에서의 call은 bearer가 유효해도 403 ip_not_allowed로 거부됩니다. kaleidr.com/api-keys에서 관리하세요.