API-Schlüssel erhalten

Kaleidr ist eine Plattform, ein SDK und ein Zugriffssystem — für KI, Karten und Design, gesteuert über Capability-Scopes. Ein Schlüssel ist in zwei sicheren Formen verfügbar, abhängig davon, wo er eingesetzt wird; beide gehören zur selben Organisation und werden gegen dasselbe Kontingent abgerechnet.

Form	Präfix	Einsatzort	Funktion
Publishable (Browser)	kld_pk_live_…	in HTML, dem SDK, <kaleidr-map>	Origin-gebunden und sicher im Seitenquelltext. Das SDK tauscht ihn zur Laufzeit gegen eine kurzlebige Session aus. Kann nicht als Server-Bearer verwendet werden oder Schlüssel verwalten.
Server (Backend)	kld_sk_live_…	nur auf deinen Servern	Vollständiger Bearer für Server-zu-Server-Aufrufe; optionale IP-Allowlist, Limits und Ablaufdatum. Im Browser blockiert (403 server_key_in_browser).

Bestehende ältere kld_live_…-Schlüssel authentifizieren weiterhin unverändert.

Was jeder Plan erlaubt

Dies ist die kanonische Richtlinie Plan → Scope × Produkt. Diese Tabelle wird mit B2B_TIER_API_CAPABILITIES in @kaleidr/shared-types synchron gehalten — derselben Konstante, die shared-api beim Erstellen eines Schlüssels und inference-api beim Session- Austausch liest — durch einen CI-Drift-Guard. Dadurch kann eine Zeile hier nicht unbemerkt von dem abweichen, was die Plattform tatsächlich erlaubt.

Plan	Publishable	Server	Zugelassene Scopes	Zugelassene Produkte
Free	Ja	— (403 free_plan_publishable_only)	maps	tile
Pro	Ja	Ja	ai, maps, design, vendor*	chat, editor, viewer, tile
Enterprise	Ja	Ja	ai, maps, design, vendor*	chat, editor, viewer, tile

* vendor erfordert eine ausdrückliche Bestätigung pro Schlüssel (ansonsten 403 vendor_scope_requires_acknowledgement).

Viewer benötigt niemals einen Schlüssel — eine Share-ID ist die Berechtigung. Jeder Plan (einschließlich Free) kann einen Viewer ganz ohne Schlüssel einbetten. Das Übergeben eines Schlüssels an ein Viewer- Embed wird mit product_not_allowed abgelehnt.

Effektive Zulassung = gespeicherter Schlüssel × aktueller Tarif. Wird ein Pro-Schlüssel auf Free herabgestuft, tauscht der Server ihn gegen eine Free-geformte Session aus — nur maps-Scope und tile-Produkt. Einen Free-Schlüssel wieder zu erweitern erfordert einen neuen Schlüssel im höheren Plan, nicht die Bearbeitung des bestehenden Schlüssels (siehe Errors — Key management).

Testschlüssel

Beide Formen gibt es auch als test-Variante (kld_pk_test_…, kld_sk_test_…).

Ein Testschlüssel ist keine Sandbox. Er authentifiziert gegen dieselbe API, ruft dieselben Modelle auf und verbraucht dasselbe monatliche Kontingent wie ein Live- Schlüssel. Zwei Dinge unterscheiden sich:

• Ein Publishable-Testschlüssel kann ohne Origin-Allowlist erstellt werden, während dies bei einem Live-Schlüssel nicht möglich ist;
• ein Testschlüssel kann keine Basemap-Tiles bereitstellen.

Nutze Testschlüssel, damit Staging-Traffic separat zuordenbar und widerrufbar bleibt — darin liegt ihr tatsächlicher Wert. Behandle sie nicht als kostenlos.

Schlüssel erstellen

1. Melde dich an und öffne unter deinem Konto API Keys (kaleidr.com/api-keys) — nur für Organisations- admins.
2. Erstelle einen Schlüssel — vergib einen Namen und wähle Browser (publishable) oder Server. Bei Pro und Enterprise wird er mit der vollständigen Tarifzulassung (ai, maps, design Scopes; chat, editor, viewer, tile Produkte) erstellt; bei Free ist es ein Browser-Schlüssel, der auf maps / tile beschränkt ist, und die Server-Option wird nicht angeboten.
3. Ein Live-Browser-Schlüssel muss auf mindestens einen erlaubten Origin beschränkt sein — ein Live-Publishable-Key ohne Origins wird abgelehnt, da er sonst ein dauerhaftes Geheimnis im Seitenquelltext wäre.
4. Kopiere den Wert kld_pk_live_… / kld_sk_live_… einmal — er wird nur einmal angezeigt und danach nie wieder.

Zwei Voraussetzungen für jedes Embed

Beide sind derzeit auf keiner Produktseite dokumentiert, und jede einzelne davon kann die erste Integration vollständig blockieren.

1. Origin-Allowlist

Beim Session-Austausch wird der Origin-Header des Browsers gegen die Allowlist des Schlüssels geprüft. Bei einer Abweichung erfolgt 403 session_origin_mismatch. file:// sendet überhaupt keinen Origin — genau so wird ein kopiertes Snippet oft zuerst ausprobiert — daher muss jedes schlüsselbasierte Embed über HTTP(S) bereitgestellt werden.

Aktualisiere die Allowlist eines bestehenden Schlüssels mit einem Cognito-org-admin-JWT, nicht mit dem Plattformschlüssel selbst:

PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json

{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }

PATCH invalidiert den Snapshot-Cache des Schlüssels sofort, und das Entfernen eines Origins beendet auch bereits daran gebundene Sessions — jede Session-Anfrage prüft ihren Origin erneut gegen die aktuellen allowed_origins des Schlüssels. Daher wird die nächste Anfrage von einem entfernten Origin abgelehnt, anstatt erst nach Ablauf der TTL zu enden. Das Hinzufügen eines Origins funktioniert umgekehrt: Neue Sessions werden zugelassen, bestehende Sessions jedoch nicht rückwirkend gebunden.

2. Kunden-CSP

Die Content Security Policy deiner Seite muss die Ressourcen erlauben, die jedes Produkt lädt. Siehe Content Security Policy für eine Konfiguration pro Produkt — Tile und Viewer benötigen nur den SDK-Loader und einen Frame-Host; Chat und Editor benötigen zusätzlich 'wasm-unsafe-eval' und die Hosts des Kartenanbieters, da MapLibre im übergeordneten Dokument läuft.

Verwendung

Im Browser übergibst du den Publishable Key; das SDK tauscht ihn gegen eine kurzlebige Session aus:

<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="height:480px"></kaleidr-map>

Vom Server sendest du den Server-Schlüssel als Bearer:

Authorization: Bearer kld_sk_live_…

Der Schlüssel authentifiziert sich als deine Organisation. Nutzung wird gegen das monatliche Kontingent der Organisation abgerechnet. Siehe Auth & scopes, um zu erfahren, was jeder Scope freischaltet, und CORS & allowed origins für die Browser-Origin-Allowlist, die jeden Session-Austausch steuert.