跳到主要内容

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 管理。