Zum Hauptinhalt springen

CORS & erlaubte Origins

Publishable Keys (kld_pk_live_…) tragen eine Allowed-Origins-Liste — die Browser-Origins, die den Schlüssel verwenden dürfen. Lege sie beim Mint des Schlüssels fest (z. B. https://acme.com, https://app.acme.com); ein Live-Publishable-Key benötigt mindestens einen Eintrag. Server Keys (kld_sk_live_…) erhalten keine CORS-Freigabe, sodass eine Seite eine damit erzeugte Response niemals lesen kann. Wichtig ist, was das abdeckt und was nicht: CORS blockiert die Response, nicht die Anfrage — ein Server Key im Seitenquelltext ist unabhängig davon bereits offengelegt. Das SDK lehnt daher kld_sk_… beim Mounten ab; Server Keys sind ausschließlich für Server-zu-Server.

Durchsetzung​

  • Preflight (OPTIONS) ist permissiv — der angeforderte Origin wird gespiegelt, damit der Browser fortfährt (der Schlüssel wird bei einem Preflight nicht mitgesendet).
  • Die eigentliche Anfrage erhält nur dann einen Access-Control-Allow-Origin-Header, wenn der Request-Origin in der Allowed-Liste des Schlüssels steht. Ein nicht zugelassener Origin erhält keinen ACAO-Header, sodass der Browser die Response blockiert.

Es werden keine Cookies verwendet — die Platform API nutzt Bearer-Token-Authentifizierung, daher gibt es kein Access-Control-Allow-Credentials.

Publishable Keys reisen in URLs zum Tile-CDN​

tile.kaleidr.com nimmt deinen Publishable Key als ?key=-Query-Parameter entgegen. Das ist beabsichtigt und hat eine wichtige Konsequenz: Query Strings werden in CDN-Zugriffslogs, Browser-Historie und jedem Proxy dazwischen aufgezeichnet.

Das ist akzeptabel, weil ein Publishable Key konstruktionsbedingt öffentlich ist — er wird ohnehin in deinem Seitenquelltext ausgeliefert. Die Sicherheitskontrolle ist die Origin-Allowlist pro Schlüssel, die am Edge für jede Tile-Anfrage durchgesetzt wird, plus die Beschränkung des Schlüssels auf den maps-Scope.

Für einen Server Key ist das nicht akzeptabel. Setze niemals kld_sk_… in eine URL und beachte, dass ein geleakter Server Key bereits offengelegt ist, bevor die API ihn ablehnt.

Überall sonst — SDK-Session-Exchange, Platform API — reist der Schlüssel als Header, niemals als Query-Parameter.

Tipps​

  • Verwende Bare Origins (scheme://host[:port]) — keinen Pfad, keinen abschließenden Slash — damit sie exakt mit dem Origin-Header des Browsers übereinstimmen.
  • https ist erforderlich, außer für localhost / 127.0.0.1 (lokale Tests).
  • Server-zu-Server-Aufrufe mit einem Server Key (ohne Browser-Origin) sind nicht CORS-beschränkt, werden aber weiterhin normal authentifiziert und auf Scopes geprüft.
  • Server Keys unterstützen zusätzlich optional eine IP-Allowlist — ein Aufruf von einer IP außerhalb der Liste wird mit 403 ip_not_allowed abgelehnt, selbst wenn der Bearer gültig ist. Verwalte sie unter kaleidr.com/api-keys.