跳至主要内容

CORS 與允許的 origins

Publishable key（kld_pk_live_…）帶有 allowed-origins 清單 — 允許使用該 key 的 browser origins。在 mint key 時設定它（例如 https://acme.com, https://app.acme.com）；live publishable key 至少需要 一個。Server key（kld_sk_live_…）不會取得 CORS grant，因此頁面 永遠無法讀取使用它產生的 response。請注意它涵蓋與不涵蓋的範圍： CORS 阻擋的是 response，不是 request — 一旦 server key 被嵌入 page source，就已經暴露。因此 SDK 會在 mount 時拒絕 kld_sk_…；server key 僅供 server-to-server 使用。

如何執行​

  • Preflight (OPTIONS) 是 permissive 的 — 它會反映 requested origin， 讓瀏覽器繼續（preflight 中不會提交 key）。
  • 實際 request 只有在 request Origin 位於 key 的 allowed list 時， 才會取得 Access-Control-Allow-Origin header。不在 allowlist 的 origin 不會取得 ACAO header，因此瀏覽器會阻擋 response。

不涉及 cookies — 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 logs、browser history 與中間的任何 proxy。

這是可以接受的，因為 publishable key 從設計上就是公開的 — 它 本來就會隨 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 origins（scheme://host[:port]）— 不含 path、不含 trailing slash — 才能與瀏覽器 Origin header 完全相符。
  • 除 localhost / 127.0.0.1（本機測試）之外，必須使用 https。
  • 使用 server key 的 server-to-server call（沒有 browser Origin） 不受 CORS gate 限制，但仍會正常進行 auth + scope check。
  • Server key 還支援選用的 IP allowlist — 從清單外 IP 發出的 call 即使 bearer 有效，也會被 403 ip_not_allowed 拒絕。 請在 kaleidr.com/api-keys 管理。