API-Schlüssel erhalten

Ein API-Schlüssel identifiziert Ihre Organisation gegenüber Kaleidr. Jede Anfrage aus einem Browser oder von einem Server wird anhand des Tarifs Ihrer Organisation zugelassen und auf deren Nutzung angerechnet. Schlüssel erstellen und verwalten Sie unter kaleidr.com/api-keys.

Für Chat, Editor, Tile und die Server-API brauchen Sie einen Schlüssel. Für die Einbettung einer veröffentlichten Karte mit Viewer benötigen Sie keinen: Die Karten-ID genügt.

Die zwei Schlüsseltypen

Es gibt zwei Schlüsseltypen. Welcher passend ist, hängt davon ab, wo der verwendende Code ausgeführt wird.

	Veröffentlichbarer Schlüssel	Serverschlüssel
Präfix	kld_pk_live_…	kld_sk_live_…
Einsatzort	Webseite: SDK und <kaleidr-map>-Element	Ausschließlich auf Ihren Servern
Im Seitenquelltext sicher?	Ja	Nein. Wie ein Passwort behandeln.
Verwendung	Das SDK tauscht ihn gegen ein kurzlebiges Sitzungstoken aus; damit erfolgen die Aufrufe	Direkt bei jeder Anfrage als Authorization: Bearer oder X-Api-Key übermittelt
Einschränkungen	Websites auf der Liste zulässiger Ursprünge	Einschränkungen über die Schlüssel-API, etwa eine IP-Zulassungsliste
Tarife	Free, Pro, Enterprise	Pro, Enterprise
Bezeichnung auf API Keys	Browser / Embed Key	Server Key

Verwenden Sie einen veröffentlichbaren Schlüssel für alles, was im Browser eines Besuchers läuft. Er darf sichtbar sein. Schutz bieten die Liste zulässiger Ursprünge und die Tatsache, dass er die API nicht selbst aufrufen kann: Direkte Aufrufe eines Endpunkts mit diesem Schlüssel werden mit 401 publishable_requires_session zurückgewiesen.

Verwenden Sie einen Serverschlüssel, wenn Ihr Backend Kaleidr aufruft, etwa zur Adressgeokodierung, zum Streamen einer Antwort über eine API-Route oder im Backend einer mobilen App. Ein Serverschlüssel wird bei Anfragen mit Origin-Header abgewiesen (403 server_key_in_browser), wie ihn Browser senden; auch das SDK verweigert schon vor der ersten Anfrage das Mounten. Geben Sie Serverschlüssel niemals in eine Webseite oder das Binärpaket einer mobilen App.

Beide Schlüsseltypen gehören derselben Organisation und greifen auf dieselben Nutzungskontingente zu. So funktioniert Kaleidr erläutert Sitzungen, Organisationen und Abrechnung.

Vor Einführung der beiden Typen erzeugte Schlüssel beginnen mit kld_live_. Sie funktionieren weiterhin und werden wie Serverschlüssel direkt gesendet.

Was die einzelnen Tarife erlauben

Der Tarif Ihrer Organisation bestimmt, welche Schlüsseltypen erstellt werden dürfen, welche Berechtigungen ein Schlüssel haben und welche Produkte er einbinden kann.

Tarif	Veröffentlichbar	Server	Zulässige Berechtigungen	Zulässige Produkte
Free	Ja	— (403 free_plan_publishable_only)	ai, maps, design	chat, editor, viewer, tile
Pro	Ja	Ja	ai, maps, design	chat, editor, viewer, tile
Enterprise	Ja	Ja	ai, maps, design, vendor*	chat, editor, viewer, tile

* vendor ist nie standardmäßig enthalten und steht nur Enterprise-Schlüsseln zur Verfügung. Siehe Berechtigungen.

Außerdem begrenzt jeder Tarif die Anzahl aktiver Schlüssel pro Organisation:

Tarif	Aktive Schlüssel
Free	2
Pro	10
Enterprise	25

Bei Überschreitung wird das Erstellen mit 409 key_limit_reached abgewiesen. Widerrufen Sie einen Schlüssel, um einen weiteren zu erstellen. Eine Rotation zählt nicht als Neuerstellung; der alte Schlüssel zählt aber bis zum Ende seiner Übergangsfrist weiter.

Fünf wichtige Hinweise zu dieser Tabelle:

• Free unterstützt alle Browser-Produkte. Free-Organisationen dürfen Chat, Editor, Tile und Viewer auf ihrer Website einsetzen. Chat-Antworten verbrauchen das monatliche KI-Guthaben des Free-Tarifs. Ist es aufgebraucht, antwortet die API bis zum nächsten Abrechnungszeitraum, einem Zusatzpaket oder einem Upgrade mit 429.
• Viewer steht in der Tabelle, weil der Tarif es erlaubt, nicht weil ein Schlüssel benötigt wird. Veröffentlichte Karten können in jedem Tarif schlüssellos eingebettet werden.
• Pro ergänzt Serverschlüssel und höhere Schlüsselzahlen. Eine Pro-Organisation kann Serverschlüssel fürs Backend erstellen und statt 2 bis zu 10 aktive Schlüssel halten; zulässige Berechtigungen und Produkte entsprechen Free.
• Eigene Geschäftsdaten in KI-Antworten sind in beiden Zugriffswegen Enterprise vorbehalten. Eigentümer oder Administratoren können Geschäftsdaten im Rahmen ihrer vertraglichen Grenzen hochladen. Der Studio-Assistent verwendet sie für angemeldete Mitglieder der Organisation; Free und Pro können keine solchen Daten hochladen. Auch das Abfragen über API oder SDK mit der Berechtigung vendor steht nur Enterprise offen. Ein Versuch, in Free oder Pro einen Schlüssel mit vendor zu erstellen, führt zu 403 tier_capability_not_allowed. Ihre Daten erläutert den Ablauf.
• Datensätze lassen sich in jedem Tarif einer Studio-Karte hinzufügen. Angemeldete Benutzer laden Tabellen und Geodateien im Bereich Data hoch. In Free gelten 50.000 Zeilen je Datensatz, 32 MiB je Datei und 250.000 Zeilen insgesamt. Pro erlaubt 100.000 Zeilen, 64 MiB und 5.000.000 Zeilen. Enterprise hat dieselben Grenzen je Datensatz und Datei wie Pro (100.000 Zeilen, 64 MiB); das Gesamtkontingent steht im Vertrag. Die Daten erscheinen auf Karten in Studio und bei Besuchern veröffentlichter Karten und können vom Studio-KI-Assistenten berücksichtigt werden, sind aber nicht über einen API-Schlüssel abrufbar. Siehe Kartendatensätze.

Tarifpreise und Kontingente stehen auf der Preisseite. Für Enterprise werden die Grenzen individuell vereinbart.

Berechtigungen

Ein Scope ist eine Berechtigung, die ein Schlüssel trägt. Jedes Produkt bzw. jeder Endpunkt prüft den benötigten Scope.

Scope	Erlaubte Funktionen	Bei neuem Schlüssel
ai	Chat sowie Chat-, Orts- und Geokodierungsendpunkte der Server-API	Enthalten
maps	Tile-Basiskartensitzungen	Enthalten
design	Editor und Design-Endpunkte der Server-API	Enthalten
vendor	Chat-Antworten auf Grundlage veröffentlichter Geschäftsdaten Ihrer Organisation	Nicht enthalten; muss angefordert werden. Nur Enterprise.

Über die Seite API Keys erstellte Schlüssel erhalten immer ai, maps und design; dort gibt es keine Scope-Auswahl. Um vendor (nur Enterprise) hinzuzufügen oder Standardscopes auszulassen, verwenden Sie die Schlüssel-API.

Scopes werden beim Erstellen festgelegt. Sie lassen sich später nicht ändern. Bei einer Rotation bleiben sie erhalten, mit zwei Ausnahmen: Scopes, die der aktuelle Tarif nicht mehr zulässt, werden weggelassen; unter Free erhält der Ersatz immer den gesamten Funktionsumfang von Free (siehe Tarifwechsel). Zum Ändern erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Wenn sich Ihr Tarif ändert

Welche Aktionen ein Schlüssel erlaubt, ergibt sich aus der Schnittmenge seiner Berechtigungen und der im aktuellen Tarif erlaubten Funktionen. Dies wird bei jeder Anfrage überprüft.

Von Enterprise zu Pro oder Free. Bestehende Schlüssel funktionieren weiter. Ein Schlüssel mit vendor behält den Scope in seinen gespeicherten Einstellungen, der Zugriff greift aber nicht mehr: Antworten enthalten keine eigenen Geschäftsdaten mehr. Ein Fehler wird nicht angezeigt, die Antworten basieren auf Allgemeinwissen. Zuvor ausgegebene Browsersitzungen enden: Die nächste Anfrage erhält 401, und das SDK bezieht eine neue Sitzung unter dem neuen Tarif. In Pro erzeugt die Rotation eines solchen Schlüssels einen Ersatz ohne vendor; andere Scopes und die Produktliste bleiben gleich. Neue Geschäftsdaten-Uploads werden mit 403 vendor_data_not_on_plan abgewiesen. Eigentümer und Administratoren können vorhandene Releases dennoch auflisten, zurückziehen und löschen.

Wechsel zu Free. In Free lassen sich weder neue Serverschlüssel anlegen noch vorhandene Server- oder Legacy-Schlüssel rotieren: 403 free_plan_publishable_only. Die Rotation eines veröffentlichbaren Schlüssels erzeugt unabhängig von dessen früheren Einstellungen einen Ersatz mit allen Free-Berechtigungen (ai, maps, design und allen vier Produkten). Bestehende Studio-Datensätze bleiben erhalten; neue Uploads unterliegen den Free-Datensatzgrenzen. Vor dem Wechsel ausgegebene Browsersitzungen enden ebenfalls, und das SDK erneuert sie.

Bei einem späteren Upgrade werden die im neuen Tarif verfügbaren Funktionen wieder erlaubt. Ein Schlüssel, in dessen Einstellungen vendor noch steht, erhält auf Enterprise erneut Datenzugriff. Ein bei niedrigerem Tarif rotierter Ersatz erhält den Scope nicht automatisch zurück; erstellen Sie einen neuen Schlüssel.

Schlüssel erstellen

Sie müssen Eigentümer oder Administrator Ihrer Organisation sein.

1. Melden Sie sich bei kaleidr.com an und öffnen Sie kaleidr.com/api-keys. Unter Your API Keys sind die Schlüssel Ihrer Organisation aufgelistet.
2. Wählen Sie Create Key. Es erscheint der Dialog Create a Key mit drei Feldern.
3. Key Name. Geben Sie eine Bezeichnung wie Production site ein. Besucher sehen sie nicht. Benennen Sie Schlüssel nach ihrem Einsatzort, damit Sie sie beim Widerrufen unterscheiden können.
4. Key Type. Wählen Sie Browser / Embed Key (veröffentlichbar) oder Server Key. In Free gibt es die Option Server Key nicht. Der Typ lässt sich später nicht ändern.
5. Allowed Origins. Geben Sie für veröffentlichbare Schlüssel die zulässigen Websites kommagetrennt ein, z. B. https://www.example.com, https://app.example.com. Ein leeres Feld erlaubt alle Websites. Das Format steht unter Zulässige Ursprünge. Serverschlüssel sind nicht an eine Website gebunden; lassen Sie das Feld dafür leer.
6. Wählen Sie Create Key.
7. Kopieren Sie den Schlüssel jetzt. Der vollständige Wert erscheint nur einmal mit dem Hinweis „Copy this key now — it won't be shown again.“ Klicken Sie Copy, speichern Sie ihn sicher und wählen Sie Done. Kaleidr speichert den vollständigen Wert nicht. Bei Verlust müssen Sie den Schlüssel rotieren.

Erwartetes Ergebnis: Der neue Schlüssel steht in der Tabelle, unter Key mit seinen Anfangszeichen, daneben Name, Typ (Browser oder Server), Status Active und heutiges Datum.

Erscheint "You must be an organization admin to manage API keys.", bitten Sie einen Eigentümer oder Administrator, den Schlüssel zu erstellen oder Ihre Rolle anzupassen.

Zulässige Ursprünge

Die Liste zulässiger Ursprünge bestimmt, von welchen Websites ein veröffentlichbarer Schlüssel verwendet werden kann. Beim Sitzungsaustausch übermittelt der Browser den Ursprung der Seite im Origin-Header; Kaleidr gleicht ihn mit der Liste ab.

• Eine leere Liste erlaubt jede Website. Das erleichtert die Entwicklung, aber wer den Schlüssel aus dem Seitenquelltext kopiert, kann ihn auf der eigenen Website verwenden und Ihr Kontingent verbrauchen. Legen Sie für jeden Produktionsschlüssel eine Liste fest.
• Eine Liste mit mindestens einem Eintrag erlaubt nur die angegebenen Ursprünge. Der Abgleich ist exakt: https://example.com deckt https://www.example.com nicht ab, und http://localhost:3000 nicht http://localhost:5173. Tragen Sie jeden Ursprung einzeln ein.

Ein Ursprung besteht aus Schema, Host und optionalem Port, ohne Pfad:

Eintrag	Zulässig
https://www.example.com	Ja
https://app.example.com:8443	Ja
http://localhost:8000	Ja. http ist nur für localhost und 127.0.0.1 zulässig. http://[::1] lässt sich über die Schlüsselverwaltungs-API festlegen, nicht über diese Seite.
http://www.example.com	Nein. Außerhalb des lokalen Hosts ist https erforderlich.
https://www.example.com/store	Nein. Ein Ursprung hat keinen Pfad.
*.example.com	Nein. Platzhalter werden nicht unterstützt. https://*.example.com wird wörtlich gespeichert und passt zu keiner Website.

Ein Schlüssel kann höchstens 100 Ursprünge enthalten.

Zum Bearbeiten der Liste klicken Sie in der Schlüsselzeile auf das Stiftsymbol. Im Dialog Edit Key ändern Sie Allowed Origins und wählen Save changes. Dort können Sie den Schlüssel auch umbenennen.

• Ein hinzugefügter Ursprung gilt für neue Sitzungen dieser Website.
• Wird ein Ursprung entfernt, wird die Website gesperrt. Bereits ausgestellte Sitzungen von dort scheitern bei der nächsten Anfrage mit 401 Invalid or missing API key, statt bis zum Ablauf weiterzulaufen.

So sieht eine blockierte Website aus. Versucht eine Seite mit einem nicht gelisteten Ursprung ein Produkt einzubinden, lehnt die Sitzungsaushandlung mit 403 origin_not_allowed ab. Die Antwort enthält keine CORS-Header. Daher meldet der Browser für …/b2b/v1/sdk/sessions einen CORS-Fehler, das SDK protokolliert [kaleidr:<product>] und nichts wird dargestellt. Unter Fehlerbehebung finden Sie den genauen Wortlaut.

Die Liste begrenzt die Verwendung des Schlüssels im Browser; sie macht den veröffentlichbaren Schlüssel nicht geheim. Nicht-Browser-Clients können beliebige Werte im Origin-Header senden. Das Sicherheitsmodell erläutert Schutz und Grenzen, CORS und zulässige Ursprünge die Anfragedetails.

Schlüssel rotieren und widerrufen

Rotieren Sie einen Schlüssel, um ihn ohne Ausfallzeit zu ersetzen. Wählen Sie die Rotationsaktion seiner Zeile und bestätigen Sie. Kaleidr erstellt einen Ersatz desselben Typs mit denselben Scopes und Ursprüngen und zeigt seinen Wert einmal an. Der alte Schlüssel funktioniert noch 24 Stunden, damit Sie den neuen bereitstellen können. Während dieser Frist zählt der alte weiterhin zum Schlüssellimit und lässt sich nicht erneut rotieren.

Rotieren Sie Schlüssel, wenn eine zugriffsberechtigte Person ausscheidet, oder nach dem Zeitplan Ihrer Sicherheitsrichtlinie. Bei einem kompromittierten Schlüssel widerrufen Sie ihn: Die Rotation über die Seite lässt den alten Wert 24 Stunden lang gültig.

Widerrufen Sie einen Schlüssel, um ihn sofort zu sperren. Wählen Sie das Papierkorbsymbol seiner Zeile und bestätigen Sie. Die Warnung lautet: „Revoke this API key? Any site using it will stop working immediately.“ Auch alle zugehörigen Sitzungen enden; bereits geöffnete Seiten scheitern bei ihrer nächsten Anfrage. Ein widerrufener Schlüssel kann nicht wiederhergestellt werden.

Bei einem geleakten Serverschlüssel sollten Sie widerrufen, nicht rotieren: Die 24-stündige Übergangsfrist würde den kompromittierten Wert weiter zulassen.

Testschlüssel

Beide Schlüsseltypen gibt es auch als Testvariante: kld_pk_test_… und kld_sk_test_….

Ein Testschlüssel ist keine Sandbox. Er spricht dieselbe API an, erhält dieselben Antworten und verbraucht dieselben KI-Guthaben und Kartenladungen wie ein Live-Schlüssel. Ein Unterschied: Er kann keine Basiskartenkacheln laden.

Der Vorteil ist die Trennung: Der Datenverkehr Ihrer Staging-Seite läuft über einen eigenen Schlüssel, den Sie unabhängig von der Produktion widerrufen können. Testverkehr ist nicht kostenlos.

Die Seite API Keys erstellt nur Live-Schlüssel. Für einen Testschlüssel verwenden Sie die Schlüssel-API mit "environment": "test".

Optionen, die die Seite nicht anbietet

Auf der Seite API Keys lassen sich Name, Typ und zulässige Ursprünge festlegen. Weitere Einstellungen bietet die Schlüssel-API unter https://api.kaleidr.com/shared-api/api-keys.

Die Schlüssel-API authentifiziert Sie persönlich, nicht einen API-Schlüssel: Übergeben Sie das Zugriffstoken eines angemeldeten Eigentümers oder Administrators als Authorization: Bearer. Mit einem API-Schlüssel lassen sich keine Schlüssel erstellen oder ändern.

Feld	Typ	Standard	Funktion
name	Zeichenfolge, 1–200 Zeichen	erforderlich	Bezeichnung des Schlüssels.
org_id	UUID	Ihre primäre Organisation	Organisation, für die der Schlüssel erstellt wird. Im Anfragekörper senden: Ein org_id in der Abfrage wird beim Erstellen ignoriert.
key_type	"publishable" oder "server"	"publishable"	Schlüsseltyp; nach Erstellung unveränderlich.
environment	"live" oder "test"	"live"	Erstellt einen Live- oder Testschlüssel. Danach unveränderlich.
scopes	Array von Zeichenfolgen	["ai", "maps", "design"]	Berechtigungen des Schlüssels; nach Erstellung unveränderlich.
vendor_acknowledged	boolesch	false	Muss true sein, um einen veröffentlichbaren Schlüssel mit vendor zu erstellen.
allowed_origins	Array von Zeichenfolgen, bis zu 100	[]	Zulässige Ursprünge; nur für veröffentlichbare Schlüssel.
allowed_products	Array von Zeichenfolgen	[] (alle Produkte)	Begrenzt auf einige von chat, editor, viewer, tile. Gilt für jeden Schlüsseltyp; siehe Hinweis unten.
allowed_ips	Array von Zeichenfolgen, bis zu 100	[] (jede Adresse)	IP-Adressen oder CIDR-Bereiche für Serverschlüssel.
monthly_cap_tokens	Ganzzahl ab 0	keiner	Höchstzahl KI-Credits pro Abrechnungszeitraum für diesen Schlüssel. Ab 1 gilt ein Limit, 0 oder null bedeutet kein Limit.
expires_at	zukünftiger Zeitstempel	keiner	Zeitpunkt, ab dem der Schlüssel nicht mehr funktioniert.

Im Free-Tarif werden scopes und allowed_products stets auf alle erlaubten Funktionen gesetzt (ai, maps, design; chat, editor, viewer, tile), unabhängig von den Werten der Anfrage. Das gilt auch bei Rotationen in Free. In jedem Tarif führt die Angabe eines nicht zulässigen Scopes oder Produkts zu 403 tier_capability_not_allowed; es wird nichts stillschweigend weggelassen.

Produktbeschränkungen gelten bei jeder Verwendung eines Schlüssels. Versucht ein veröffentlichbarer Schlüssel, außerhalb seiner Produktliste ein Produkt einzubinden, lehnt der Sitzungsaustausch mit 403 product_not_allowed ab. Bei Server- oder Legacy-Schlüsseln wird jeder Aufruf eines Endpunkts für ein nicht erlaubtes Produkt mit demselben 403 product_not_allowed abgewiesen. Chat-, Orts- und Geokodierungsendpunkte gehören zu chat, Design-Endpunkte zu editor. Ein Serverschlüssel für alle von seinen Scopes zugelassenen Endpunkte benötigt leere allowed_products. Siehe Tabelle unter Authentifizierung und Scopes.

Diese Anfrage erstellt einen veröffentlichbaren Testschlüssel, der auf Chat auf einer einzigen Staging-Website beschränkt ist:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging site chat",
    "key_type": "publishable",
    "environment": "test",
    "allowed_origins": ["https://staging.example.com"],
    "allowed_products": ["chat"]
  }'

Die Antwort 201 enthält die Einstellungen und nur dieses eine Mal den vollständigen Wert in plaintext_key:

{
  "id": "5f0c2a9e-…",
  "name": "Staging site chat",
  "key_prefix": "kld_pk_test_…",
  "key_type": "publishable",
  "environment": "test",
  "scopes": ["ai", "maps", "design"],
  "allowed_origins": ["https://staging.example.com"],
  "allowed_products": ["chat"],
  "allowed_ips": [],
  "monthly_cap_tokens": null,
  "status": "active",
  "expires_at": null,
  "plaintext_key": "kld_pk_test_…"
}

Ein Schlüssel mit Zugriff auf Ihre Geschäftsdaten

Mit dem Scope vendor kann Chat Antworten auf veröffentlichten Geschäftsdaten Ihrer Organisation aufbauen. Sowohl das Hochladen dieser Daten als auch Schlüssel, die sie abrufen dürfen, sind ausschließlich unter Enterprise verfügbar. Der Scope wird nur über die Schlüssel-API erteilt:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site chat with our data",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

vendor_acknowledged ist nötig, weil ein veröffentlichbarer Schlüssel im Seitenquelltext steht: Jeder Besucher kann Chat Fragen stellen, und Antworten können Ihre hochgeladenen Daten enthalten. Mit true bestätigen Sie ausdrücklich, dass Sie das beabsichtigen.

• Ein veröffentlichbarer Schlüssel mit vendor ohne "vendor_acknowledged": true wird mit 422 vendor_scope_requires_acknowledgement abgewiesen.
• Für Serverschlüssel ist keine Bestätigung nötig.
• In Free und Pro wird jede Anfrage mit vendor unabhängig von vendor_acknowledged mit 403 tier_capability_not_allowed abgelehnt. Es wird kein Schlüssel erstellt.

Ihre Daten erläutert das Hochladen und die Prüfung, ob eine Antwort Daten verwendet hat.

Beim Ändern (PATCH /shared-api/api-keys/{id}) werden name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens und expires_at akzeptiert. Bei der Rotation (POST /shared-api/api-keys/{id}/rotate) kann grace_hours zwischen 0 und 8760 liegen; mit dem Standard 0 wird der alte Schlüssel sofort abgeschaltet. Widerrufen wird mit POST /shared-api/api-keys/{id}/revoke. Die möglichen Fehlercodes stehen unter Fehler.

Zwei Voraussetzungen für jede Einbettung

Selbst ein korrekter Schlüssel reicht nicht aus, damit ein schlüsselpflichtiges Produkt erscheint. Zwei Bedingungen der Seite müssen ebenfalls erfüllt sein; Browserfehlermeldungen benennen deren Ursache nicht immer eindeutig.

1. Die Seite stammt von einem für den Schlüssel zulässigen Ursprung

• Stellen Sie die Seite über HTTP oder HTTPS bereit, auch bei der Entwicklung. Eine lokale Datei (file://) besitzt keinen Ursprung, der für einen Schlüssel zugelassen werden kann.
• Bei einer Liste zulässiger Ursprünge muss der Ursprung Ihrer Seite exakt darin stehen: Schema, Host und Port. Für lokale Entwicklung ist das gewöhnlich http://localhost:<port>.

Andernfalls wird nichts angezeigt, und die Konsole meldet einen CORS-Fehler beim Sitzungsaustausch. Das wirkt wie ein Netzwerkfehler, liegt aber an der Ursprungsliste.

2. Die Content Security Policy erlaubt die Ressourcen des Produkts

Sendet Ihre Website einen Content-Security-Policy-Header, muss sie die für jedes Produkt benötigten Kaleidr-Hosts zulassen. Ohne einen solchen Header ist keine Einstellung notwendig.

Produkt	Was die Richtlinie erlauben muss
Viewer, Tile	Skripte von https://cdn.kaleidr.com, einen Frame von https://map-embed.kaleidr.com und bei Schlüsselverwendung Verbindungen zu https://api.kaleidr.com
Chat, Editor	Skripte von https://cdn.kaleidr.com, Verbindungen zu https://api.kaleidr.com sowie Inline-Stile, da beide Produkte CSS in die Seite einfügen. Editor lädt außerdem seine Basiskarte von https://tile.kaleidr.com.

Unter Content Security Policy finden Sie alle nötigen Direktiven für jedes Produkt.

Bei einer Sperre meldet der Browser Refused to load… oder Refused to connect… und nennt die blockierte Adresse und Direktive.

Schlüssel verwenden

Auf einer Webseite übergeben Sie dem Produkt einen veröffentlichbaren Schlüssel. Das SDK tauscht ihn gegen eine Sitzung und verlängert sie, solange das Produkt eingebunden ist.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

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

Erwartetes Ergebnis: Die Basiskarte erscheint und im Netzwerk-Tab steht für https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions die Antwort 200. Die Schnellstartanleitung enthält für jedes Produkt eine vollständige Beispielseite.

Vom Server aus senden Sie bei jeder Anfrage einen Serverschlüssel. Dieser Aufruf listet die Kartenstile der Design-Endpunkte auf und verbraucht keine KI-Credits. Er eignet sich daher als erster Funktionstest.

curl https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer kld_sk_live_…"

Erwartetes Ergebnis: 200 mit einem JSON-Objekt, das ein Array styles enthält. 401 mit {"detail":"Invalid or missing API key"} bedeutet: Schlüssel falsch oder widerrufen. 403 mit {"detail":"server_key_in_browser"} bedeutet, dass die Anfrage einen Origin-Header enthält; entfernen Sie ihn. Weiteres zeigt der Server-Schnellstart.

Nächste Schritte

• Schnellstart: je eine funktionierende Seite für Chat, Viewer und Tile.
• So funktioniert Kaleidr: Sitzungen, Organisationen und die beiden Nutzungskontingente.
• Authentifizierung und Scopes: wie Anmeldedaten gesendet und geprüft werden.
• Produktionscheckliste: ein Schlüssel je Website, zulässige Ursprünge und alles Weitere vor dem Start.