Authentifizierung und Scopes

Jeder Aufruf der Kaleidr-Plattform-API enthält einen Zugangsnachweis. Es gibt drei Arten, die von der API unterschiedlich behandelt werden:

• Ein veröffentlichbarer Schlüssel identifiziert Ihre Organisation im Browser. Er kann die API nicht unmittelbar aufrufen, sondern wird gegen eine Sitzung eingetauscht.
• Ein Sitzungstoken dient dem Browser für tatsächliche API-Aufrufe. Es ist kurzlebig und an einen Website-Ursprung und ein Produkt gebunden.
• Ein Serverschlüssel ist ein geheimer Schlüssel, den Ihr Backend direkt bei jeder Anfrage überträgt.

Diese Seite beschreibt die Übertragung der Zugangsdaten, den Sitzungsaustausch, die Berechtigungen der Scopes, die Vergabe von vendor sowie alle Authentifizierungsfehler samt Ursache und Lösung. Informationen zu den Folgen eines kompromittierten Schlüssels finden Sie im Sicherheitsmodell.

Arten von Zugangsdaten

Zugangsdaten	Präfix	Speicherort	Verwendung	Tarif
Veröffentlichbarer Schlüssel	kld_pk_live_…	Quelltext der Seite	Einmalig an den Sitzungsaustausch gesendet; an allen anderen Endpunkten abgelehnt	Free, Pro, Enterprise
Sitzungstoken	kld_sess_live_…	Browserspeicher	Bei jedem Laufzeitaufruf von der Seite gesendet, für die es ausgestellt wurde	Aus einem veröffentlichbaren Schlüssel oder einer veröffentlichten Karte erstellt
Serverschlüssel	kld_sk_live_…	Ausschließlich im Backend	Bei jedem Laufzeitaufruf gesendet; abgelehnt, wenn die Anfrage einen Origin-Header enthält	Pro, Enterprise
Legacy-Schlüssel	kld_live_…	Ihr Backend	Direkte Zugangsdaten wie ein Serverschlüssel; eine Rotation erzeugt einen Serverschlüssel	Nur bestehende Schlüssel

Über die Schlüsselverwaltungs-API mit environment: "test" erzeugte Schlüssel enthalten test statt live (kld_pk_test_…, kld_sk_test_…). Ein Testschlüssel kann keine Basiskarten-Kacheln laden.

Ein Schlüssel wird bei seiner Erstellung oder Rotation genau einmal vollständig angezeigt. Kaleidr speichert nur einen Hash. Verlorene Schlüssel können daher nicht wiederhergestellt werden; rotieren Sie sie.

Zugangsdaten übertragen

Senden Sie den Zugangsnachweis in einem der beiden Header. Beide werden von jedem Endpunkt akzeptiert.

Authorization: Bearer kld_sk_live_…

X-Api-Key: kld_sk_live_…

Wenn beide Header vorhanden sind, verwendet die API Authorization, sofern dessen Wert mit einem Kaleidr-Präfix beginnt; andernfalls liest sie X-Api-Key. Schreiben Sie niemals einen Serverschlüssel in eine URL.

Welche Laufzeitendpunkte die einzelnen Zugangsdaten nutzen können (alle Endpunkte außer dem Sitzungsaustausch):

Zugangsdaten	Ergebnis an einem Laufzeitendpunkt
Veröffentlichbarer Schlüssel	401 publishable_requires_session. Tauschen Sie ihn zuerst ein.
Serverschlüssel ohne Origin-Header	Akzeptiert, dann Prüfung von IP-Zulassungsliste, Scope, erlaubten Produkten, Kontingent und Ratenlimit.
Serverschlüssel mit Origin-Header	403 server_key_in_browser. Browser ergänzen Origin bei standortübergreifenden Anfragen; so erkennt die API einen Serverschlüssel auf einer Webseite.
Sitzungstoken vom ursprünglichen Ursprung	Akzeptiert.
Sitzungstoken mit anderem Origin	403 session_origin_mismatch.
Sitzungstoken einer veröffentlichten Karte ohne Origin	403 session_origin_mismatch.

Das JavaScript-SDK setzt dieselbe Regel früher durch: Kaleidr.mount weist einen kld_sk_…-Schlüssel im Browser ab, ohne eine Anfrage zu senden.

Sitzungsaustausch

Ein veröffentlichbarer Schlüssel wird an einem Endpunkt gegen ein Sitzungstoken eingetauscht. Das SDK übernimmt dies bei jeder Einbindung mit Schlüssel und erneuert das Token. Nur beim Bau eines eigenen Browserclients müssen Sie diesen Endpunkt selbst aufrufen.

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
X-Api-Key: kld_pk_live_…
Content-Type: application/json

{ "product": "chat" }

product ist erforderlich und muss chat, editor, viewer oder tile sein. Die Anfrage benötigt einen Origin-Header, den der Browser automatisch hinzufügt.

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

Feld	Bedeutung
session_token	Zugangsdaten für Laufzeitaufrufe. Format: kld_sess_{env}_{token}.
expires_in	Gültigkeitsdauer in Sekunden. Eine Sitzung mit Schlüssel gilt 900 Sekunden. Lesen Sie diesen Wert aus, statt ihn fest zu codieren.
product	Das Produkt, an das die Sitzung gebunden ist.
basemap_style_id	Die Standardbasiskarte Ihrer Organisation oder null, falls keine definiert ist.

Bindungen einer Sitzung

• Ein Ursprung. Der Origin der Austauschanfrage. Aufrufe von anderen Ursprüngen werden abgelehnt.
• Ein Produkt. Eine tile-Sitzung kann keine Chat-Endpunkte aufrufen.
• Eingeschränkte Scopes. Eine Sitzung enthält nur die für ihr Produkt benötigten Scopes: ai für Chat, design für Editor, maps für Tile und keinen für Viewer. Eine Chat-Sitzung behält vendor zusätzlich, wenn der Schlüssel diesen Scope besitzt und der Tarif es erlaubt (Enterprise). Sitzungen anderer Produkte enthalten niemals vendor.

Erneuerung

Ein Client kann keine längere Gültigkeit anfordern. Tauschen Sie den Schlüssel erneut ein, bevor expires_in abläuft. Das SDK erneuert 90 Sekunden vor Ablauf, wenn ein Hintergrund-Tab sichtbar wird und die Sitzung in höchstens 90 Sekunden abläuft oder bereits abgelaufen ist, sowie alle 30 Sekunden nach einem fehlgeschlagenen Erneuerungsversuch. Scheitert bereits der allererste Austausch, schlägt die Einbindung ohne erneuten Versuch fehl.

Jeder Austausch mit product: "tile" verbraucht einen Kartenaufruf aus dem Kontingent Ihrer Organisation. Der Austausch anderer Produkte ist kostenlos. Für den Austausch gilt ein eigenes Ratenlimit pro Schlüssel, unabhängig von Laufzeitaufrufen. Siehe Kontingente und Ratenlimits.

Reihenfolge der Prüfungen

Der Austausch endet bei der ersten fehlgeschlagenen Prüfung:

Reihenfolge	Prüfung	Fehler
1	Der Schlüssel ist gültig	401 Invalid or missing API key
2	Das Ratenlimit für den Schlüsselaustausch	429 rate_limited
3	Es handelt sich um einen veröffentlichbaren Schlüssel	403 publishable_key_required
4	Die Anfrage enthält einen Origin-Header	403 origin_required
5	Der Ursprung steht gegebenenfalls auf der Zulassungsliste des Schlüssels	403 origin_not_allowed
6	Der Schlüssel ist nicht für dieses Produkt gesperrt	403 product_not_allowed
7	Ihr Tarif umfasst das Produkt	403 tier_capability_not_allowed
8	Der Schlüssel hat den für das Produkt benötigten Scope	403 insufficient_scope oder tier_capability_not_allowed, wenn der Schlüssel den Scope hat, Ihr Tarif ihn aber nicht mehr umfasst
9	Bei tile: Ein Kartenaufruf ist verfügbar	429 map_load_quota_exceeded

Test im Terminal

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

Dies funktioniert, weil Origin ein gewöhnlicher Header ist, den jeder Client außerhalb eines Browsers setzen kann. Deshalb ist die Liste erlaubter Ursprünge als Browsersteuerung und nicht als Geheimnisschutz beschrieben. Siehe CORS und erlaubte Ursprünge.

Sitzungen für veröffentlichte Karten

Eine in Studio veröffentlichte Karte, deren Kachel Kaleidr AI Control Tower oder Popup Window aktiviert, kann ihren Besuchern Chat anbieten, ohne dass ein Schlüssel in der Seite steht. Stattdessen tauscht die Seite die öffentliche ID der Karte und die Funktion ein, die sie öffnet:

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions
Content-Type: application/json

{ "share_id": "your-map-id", "feature": "control_tower" }

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

Diese Sitzung gilt ausschließlich für Chat, besitzt den Scope ai, ist 300 Sekunden gültig und wird der Organisation des Karteneigentümers berechnet. Sie enthält niemals vendor. Sie darf nur von der anfragenden Seite verwendet werden; Aufrufe ohne Origin oder mit einem anderen Ursprung werden abgelehnt. Mögliche Fehler:

Status	Code	Ursache
403	origin_required	Die Anfrage enthält keinen Origin-Header.
404	not_found	Es gibt keine veröffentlichte Karte und keinen Freigabelink mit dieser ID, oder die Karte des Freigabelinks ist nicht veröffentlicht.
403	chat_disabled	Die Kaleidr AI der Karte aktiviert die angeforderte Funktion nicht.
403	origin_not_allowed	Die Seite ist nicht unter den erlaubten Domains der Karte.
403	owner_has_no_organization	Der Karteneigentümer hat keine Organisation, der die Nutzung berechnet werden kann.
403	tier_capability_not_allowed	Der Tarif des Eigentümers umfasst keinen Chat.
429	rate_limited	Zu viele Austauschanfragen für diese Karte oder von dieser Adresse.

Die Einrichtung ist unter Kaleidr AI auf einer veröffentlichten Karte beschrieben.

Berechtigungsbereiche

Jeder Schlüssel besitzt Scopes. Jede Endpunktfamilie benötigt einen bestimmten Scope.

Scope	Freigeschaltete Funktionen	Benötigt von
ai	Endpunkte /chat/* und /retrieval/*	Chat und alle Backends, die Chat- oder Suchendpunkte aufrufen
design	Endpunkte /design/*	Editor-Sitzungen und alle Backends, die Design-Endpunkte aufrufen
maps	Basiskarten-Sitzungen	Tile
vendor	Allein keine Endpunkte. Ermöglicht Chat-Antworten aus veröffentlichten Daten Ihrer Organisation.	Chat, wenn Sie Daten hochgeladen haben

Ein neuer Schlüssel erhält ai, maps und design, sofern Sie nichts anderes anfordern. Im Free-Tarif besitzt ein Schlüssel stets den vollständigen Free-Funktionsumfang: genau diese drei Scopes und alle vier Produkte (chat, editor, viewer, tile), unabhängig von der Anfrage. vendor wird niemals standardmäßig vergeben; nur Enterprise-Organisationen können Schlüssel mit diesem Scope erstellen.

Wenn beim Erstellen eines Schlüssels ein Scope oder Produkt angefordert wird, den bzw. das Ihr Tarif nicht erlaubt, antwortet die API mit 403 tier_capability_not_allowed. Es wird kein angeforderter Bestandteil stillschweigend entfernt. Typischerweise betrifft dies vendor im Free- oder Pro-Tarif.

Scopes werden bei der Schlüsselerstellung festgelegt. Kein Endpunkt und keine Einstellung kann sie später ändern. Bei der Rotation werden sie übernommen, abzüglich aller Scopes, die Ihr aktueller Tarif nicht mehr zulässt. Zum Ändern der Scopes erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Für Rotationen im Free-Tarif gilt die Free-Regel. Der Ersatz eines rotierten veröffentlichbaren Schlüssels erhält den gesamten Free-Funktionsumfang (ai, maps, design und alle vier Produkte), unabhängig vom bisherigen Schlüssel. Server- und Legacy-Schlüssel lassen sich im Free-Tarif nicht rotieren: Die API antwortet mit 403 free_plan_publishable_only.

Die Möglichkeiten eines Schlüssels werden durch Schlüssel und Tarif gemeinsam begrenzt

Bei jeder Anfrage prüft die API die gespeicherten Scopes und Produkte des Schlüssels gegen die Leistungen, die im Tarif Ihrer Organisation heute enthalten sind. Ein Tarifwechsel verändert den Schlüssel nicht, wohl aber dessen Berechtigungen:

• insufficient_scope: Der Scope wurde dem Schlüssel nie erteilt. Lösung: Verwenden Sie einen Schlüssel mit diesem Scope.
• tier_capability_not_allowed: Der Schlüssel hat den Scope, der aktuelle Tarif umfasst ihn aber nicht. Lösung: Wechseln Sie den Tarif.

vendor ist eine Ausnahme zur zweiten Regel, da es selbst keinen Endpunkt freischaltet. Ein Schlüssel mit gespeichertem vendor, dessen Organisation unter Enterprise liegt, wird nicht zurückgewiesen: Die Anfragen funktionieren, aber die Antworten verwenden Ihre Daten nicht.

Ein Schlüssel mit leerer Produktliste darf jedes Produkt nutzen, das im Tarif enthalten ist. Ein Schlüssel ohne Scopes wird überall abgelehnt.

Eine Produktbeschränkung gilt für jeden Schlüssel

allowed_products begrenzt einen Schlüssel auf bestimmte Produkte aus chat, editor, viewer und tile. Die Einschränkung wird für jeden Schlüsseltyp jeweils bei seiner Verwendung durchgesetzt:

Schlüssel	Zeitpunkt der Prüfung	Ablehnung
Veröffentlichbarer Schlüssel	Beim Sitzungsaustausch anhand des angeforderten product	403 product_not_allowed
Server- oder Legacy-Schlüssel	Bei jeder Laufzeitanfrage anhand des Produkts, zu dem der Endpunkt gehört	403 product_not_allowed

Jede Endpunktfamilie gehört zu dem Produkt, dessen Scope sie benötigt:

Endpunkte	Scope	Produkt, das ein eingeschränkter Schlüssel zulassen muss
/chat/*, /retrieval/*	ai	chat
/design/*	design	editor

Daher wird ein mit "allowed_products": ["tile"] erstellter Serverschlüssel beim Aufruf von /chat/control/stream mit 403 product_not_allowed abgelehnt, obwohl er den Scope ai besitzt. Ein allein auf viewer begrenzter Serverschlüssel kann keinen Laufzeitendpunkt aufrufen, da eine veröffentlichte Karte keinen Schlüssel benötigt. Lassen Sie die Liste leer, wenn der Schlüssel alle durch seine Scopes erlaubten Endpunkte erreichen soll.

Ein Sitzungstoken wird hier nicht erneut geprüft: Es wurde beim Austausch bereits an sein Produkt gebunden.

	Free	Pro	Enterprise
Veröffentlichbare Schlüssel	Ja	Ja	Ja
Serverschlüssel	Nein	Ja	Ja
ai, maps, design	Ja	Ja	Ja
vendor	Nein	Nein	Ja

Pro ergänzt Free um Serverschlüssel und eine höhere Höchstzahl aktiver Schlüssel. Die vollständige Tarifübersicht finden Sie unter API-Schlüssel erhalten.

Der Scope vendor

vendor schaltet keinen eigenen Endpunkt frei. Stattdessen bestimmt der Scope, ob Chat-Antworten über diesen Schlüssel neben Kaleidrs allgemeinem Wissen auch veröffentlichte Daten Ihrer Organisation verwenden dürfen. Der gesamte Ablauf vom Upload bis zur Antwort steht unter Ihre Daten: Übersicht.

Wer kann ihn nutzen?

• Free und Pro können vendor nicht besitzen. Versucht man, einen solchen Schlüssel zu erstellen, antwortet die API mit 403 tier_capability_not_allowed, unabhängig davon, ob vendor_acknowledged übergeben wurde. Es wird kein Schlüssel erstellt.
• Enterprise kann Schlüssel mit vendor erstellen.

Der Scope regelt den Datenzugriff über einen Schlüssel. Das Hochladen ist eine separate Berechtigung für Eigentümer oder Administratoren der Organisation, nicht für Schlüssel, und ebenfalls ausschließlich Enterprise vorbehalten: Free und Pro können keine Geschäftsdaten hochladen. Dateien, die angemeldete Benutzer einer Karte in Kaleidr Studio hinzufügen, gehören zu einer anderen Funktion, die in allen Tarifen verfügbar ist; kein Scope kann diese Dateien lesen. Siehe Datensätze auf einer Karte.

Auf der API-Keys-Seite kann vendor nicht vergeben werden. Erstellen Sie den Schlüssel über die Schlüsselverwaltungs-API:

curl -s https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "store-locator-chat",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

vendor_acknowledged: true ist für einen veröffentlichbaren Schlüssel mit vendor erforderlich. Fehlt die Bestätigung, antwortet die API mit 422 vendor_scope_requires_acknowledgement. Diese Bestätigung ist nötig, weil ein veröffentlichbarer Schlüssel im öffentlich lesbaren Quelltext steht: Jeder Besucher kann daher auf die Daten zugreifen, die dieser Schlüssel lesen darf. Ein Serverschlüssel benötigt keine Bestätigung.

Bevor Sie vendor einem veröffentlichbaren Schlüssel geben:

• Verwenden Sie einen eigenen Schlüssel pro Website. Nur die Website, die aus Ihren Daten antworten muss, erhält vendor.
• Behandeln Sie sämtliche veröffentlichten Daten als öffentlich für diese Website. Veröffentlichen Sie weder Einkaufspreise noch unveröffentlichte Tarife oder Informationen, die Sie nicht selbst auf der Seite abdrucken würden.
• Beachten Sie, dass bereits laufende Sitzungen den Scope nicht nachträglich erhalten. Ein neu mit vendor erstellter Schlüssel gewährt ihn nur ab dann ausgetauschten Sitzungen.

Um vendor zu entziehen, widerrufen Sie den Schlüssel und erstellen einen Ersatz ohne diesen Scope. Der Widerruf wirkt ab der nächsten Anfrage, auch bei bereits ausgestellten Sitzungen.

Wenn eine Organisation Enterprise verlässt

Ein Wechsel von Enterprise zu Pro oder Free verändert Ihre Schlüssel nicht und führt nicht dazu, dass sie generell fehlschlagen:

Was	Nach dem Wechsel
Ein Schlüssel mit vendor	Funktioniert für alle übrigen Aufgaben weiter. Antworten greifen jedoch nicht mehr auf Ihre Daten zu. Es gibt keinen Fehler, Status oder Feldwert, der darauf hinweist.
Vor dem Wechsel ausgestellte Browser-Sitzungen	Werden beendet. Die nächste Anfrage liefert 401; das SDK holt eine neue Sitzung ohne vendor.
Rotation eines Schlüssels mit vendor	Unter Pro: erfolgreich mit 201. Der Ersatz übernimmt dieselben Scopes außer vendor; die Produktliste bleibt unverändert. Unter Free: Der Ersatz eines veröffentlichbaren Schlüssels erhält ai, maps, design und alle vier Produkte, unabhängig vom alten Schlüssel. Die Rotation eines Server- oder Legacy-Schlüssels wird mit 403 free_plan_publishable_only abgelehnt.
Erstellen eines Schlüssels mit vendor	Wird mit 403 tier_capability_not_allowed abgelehnt.
Ihre Releases	Eigentümer und Administratoren können sie in jedem Tarif weiterhin über die Upload-API auflisten, zurückziehen und löschen. Unter Free und Pro werden Hochladen und Veröffentlichen mit 403 vendor_data_not_on_plan abgelehnt.

Nach einer Rückkehr zu Enterprise kann ein Schlüssel, der vendor weiterhin gespeichert hat, wieder auf die Daten zugreifen. Ein im niedrigeren Tarif rotierter Ersatz erhält den Scope nicht zurück: Erstellen Sie einen neuen Schlüssel.

Einen Schlüssel einschränken

Einschränkung	Gilt für	Auf der API-Keys-Seite einstellbar	Über die Schlüsselverwaltungs-API einstellbar	Ablehnung
Erlaubte Ursprünge	Veröffentlichbare Schlüssel	Ja	Ja (allowed_origins)	403 origin_not_allowed beim Austausch
Erlaubte Produkte	Jeder Schlüssel	Nein	Ja (allowed_products)	403 product_not_allowed: beim Austausch eines veröffentlichbaren Schlüssels und bei jeder Laufzeitanfrage eines Server- oder Legacy-Schlüssels. Siehe Produktbeschränkungen.
IP-Zulassungsliste	Server- und Legacy-Schlüssel	Nein	Ja (allowed_ips)	403 ip_not_allowed
Monatliches Limit	Jeder Schlüssel	Nein	Ja (monthly_cap_tokens)	429 quota_exceeded
Ablaufdatum	Jeder Schlüssel	Nein	Ja (expires_at)	401 nach dem Datum
Scopes	Jeder Schlüssel	Nein	Nur bei Erstellung (scopes)	403 insufficient_scope

Erlaubte Ursprünge. Bis zu 100 Einträge, jeweils scheme://host[:port] ohne Pfad. Eine leere Liste bei einem veröffentlichbaren Schlüssel erlaubt jeden Ursprung. Details und Fehlerfälle finden Sie unter CORS und erlaubte Ursprünge.

IP-Zulassungsliste. Bis zu 100 IP-Adressen oder CIDR-Blöcke. Ein Block, der alle Adressen umfasst (/0), wird abgelehnt. Lassen Sie die Liste leer, wenn alle Adressen erlaubt sein sollen. Ist eine Liste gesetzt und kann die Absenderadresse nicht ermittelt werden, wird die Anfrage abgelehnt.

Monatliches Limit. Eine Obergrenze dafür, wie viele AI-Credits dieser Schlüssel innerhalb einer Abrechnungsperiode aus dem Kontingent Ihrer Organisation verbrauchen darf. Siehe Kontingente und Ratenlimits.

Auswirkungen auf bereits ausgestellte Sitzungen

Eine Sitzung prüft ihren übergeordneten Schlüssel bei jeder Anfrage erneut. Daher wird entzogener Zugriff schnell wirksam; das Hinzufügen von Berechtigungen erfordert einen neuen Austausch.

Änderung am Schlüssel oder Konto	Wirkung auf bereits ausgestellte Sitzungen
Schlüssel widerrufen oder ohne Übergangsfrist rotiert	401 bei der nächsten Anfrage.
Sitzungsursprung aus erlaubten Ursprüngen des Schlüssels entfernt	401 bei der nächsten Anfrage.
Sitzungsprodukt aus erlaubten Produkten des Schlüssels entfernt	401 bei der nächsten Anfrage.
Tarif herabgestuft	Zuvor ausgestellte Sitzungen erhalten 401. Danach ausgetauschte Sitzungen erhalten 403 tier_capability_not_allowed für nicht mehr enthaltene Funktionen.
Monatliches Limit hinzugefügt oder verringert	Gilt ab der nächsten Anfrage.
Monatliches Limit entfernt	Gilt ab dem nächsten Austausch.
Tarif hochgestuft	Gilt ab dem nächsten Austausch.

Da Sitzungen nur wenige Minuten gültig sind, bedeutet „ab dem nächsten Austausch“ nur eine kurze Verzögerung. Die automatische Erneuerung des SDK übernimmt die Änderung ohne Codeanpassung.

Schlüsselverwaltungs-API

Auf der Seite kaleidr.com/api-keys legen Sie den Namen, den Typ und die erlaubten Ursprünge eines Schlüssels fest. Alle anderen hier beschriebenen Einstellungen werden über dieselbe API vorgenommen, die diese Seite verwendet.

• Basis-URL: https://api.kaleidr.com/shared-api/api-keys
• Authentifizierung: Authorization: Bearer mit dem Zugriffstoken eines angemeldeten Kaleidr-Kontos, das Eigentümer oder Administrator der Organisation ist. Plattformschlüssel werden hier nicht akzeptiert. Ein eigenes langlebiges Zugangsmittel für die Schlüsselverwaltung gibt es derzeit nicht.
• Organisation: Ohne angegebene Organisation wird Ihre primäre Organisation verwendet. Für eine andere senden Sie org_id beim Erstellen im JSON-Body und bei allen anderen Routen als Query-Parameter ?org_id=. Ein Query-Parameter org_id bei der Erstellung wird ignoriert.

Methode und Pfad	Zweck	Erfolg
POST /	Schlüssel erstellen	201, Schlüsselobjekt plus plaintext_key
GET /	Aktive Schlüssel auflisten, neueste zuerst	200
GET /{id}/events?limit=1..200	Audit-Ereignisse des Schlüssels	200
PATCH /{id}	Einschränkungen ändern	200, Schlüsselobjekt
POST /{id}/rotate	Schlüssel ersetzen	201, neuer Schlüssel plus plaintext_key
POST /{id}/revoke	Schlüssel widerrufen	200, Schlüsselobjekt

Es gibt keine Löschroute. Widerrufen Sie einen Schlüssel, um ihn außer Betrieb zu nehmen.

Bei der Schlüsselerstellung akzeptierte Felder:

Feld	Typ	Standard	Hinweise
name	Zeichenfolge mit 1 bis 200 Zeichen	erforderlich
org_id	UUID	Ihre primäre Organisation	Organisation, für die der Schlüssel erstellt wird. Im Body senden; ein Query-Parameter wird auf dieser Route ignoriert.
key_type	"publishable" oder "server"	"publishable"	"server" wird unter Free mit 403 free_plan_publishable_only abgelehnt.
environment	"live" oder "test"	"live"
scopes	Zeichenfolgen-Array	["ai", "maps", "design"]	Aus ai, maps, design, vendor. Andere Werte führen zu 422 unknown_scope. Ein im Tarif nicht zugelassener Scope (vendor unter Enterprise) führt zu 403 tier_capability_not_allowed.
allowed_origins	Zeichenfolgen-Array mit bis zu 100 Einträgen	[]	Leer bedeutet bei veröffentlichbaren Schlüsseln: jeder Ursprung.
allowed_products	Zeichenfolgen-Array	[]	Aus chat, editor, viewer, tile. Leer bedeutet alle. Andere Werte führen zu 422 unknown_product. Gilt für veröffentlichbare, Server- und Legacy-Schlüssel; siehe Produktbeschränkungen.
allowed_ips	Zeichenfolgen-Array mit bis zu 100 Einträgen	[]	IP-Adressen oder CIDR-Blöcke.
monthly_cap_tokens	Ganzzahl ab 0	keine	Ab 1 begrenzt der Wert den Schlüssel; 0 oder null bedeutet ohne Limit.
expires_at	Datum und Uhrzeit in der Zukunft	keine
vendor_acknowledged	boolesch	false	Für veröffentlichbare Schlüssel mit vendor erforderlich (Enterprise).

PATCH akzeptiert name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens und expires_at. Senden Sie nur die zu ändernden Felder. Ein explizites null löscht einen Wert. scopes wird nicht akzeptiert.

rotate akzeptiert { "grace_hours": 0 } mit Werten von 0 bis 8760. Der Ersatz übernimmt die Scopes des alten Schlüssels, ausgenommen diejenigen, die Ihr aktueller Tarif nicht mehr erlaubt. Im Free-Tarif erhält er immer den gesamten Free-Funktionsumfang; Server- und Legacy-Schlüssel können nicht rotiert werden (403 free_plan_publishable_only). Bei 0 funktionieren der alte Schlüssel und seine Sitzungen sofort nicht mehr. Bei einer Übergangsfrist bleibt der alte Schlüssel bis zu deren Ende funktionsfähig, zählt weiterhin zum Limit aktiver Schlüssel Ihres Tarifs und kann nicht erneut rotiert werden. Auf der API-Keys-Seite gilt bei Rotation eine Übergangsfrist von 24 Stunden.

Die Fehler dieser Routen sind unter Fehler: Schlüsselverwaltung aufgeführt.

Authentifizierungsfehler

401 bedeutet, dass die API die Zugangsdaten überhaupt nicht akzeptiert. 403 bedeutet, dass die Identität bekannt ist, die Anfrage jedoch abgelehnt wird. Alle diese Fehler haben die Form {"detail": "<code>"}.

Bei einer im Browser wegen Zugangsdaten oder Ursprung abgelehnten Anfrage fehlt der CORS-Header. Die Seite sieht dann einen CORS-Fehler anstelle des Antwort-Bodys. Bei späterer Ablehnung wegen Scope oder Tarif ist die Antwort lesbar, und das SDK meldet kaleidr session exchange failed (403). Öffnen Sie in beiden Fällen die Anfrage im Netzwerk-Tab des Browsers, um den Fehlercode zu sehen. Siehe CORS und erlaubte Ursprünge.

Status	Code	Ursache	Lösung
401	Invalid or missing API key	Keine Zugangsdaten; unbekannter, widerrufener oder abgelaufener Schlüssel; abgelaufene Sitzung; Sitzung, deren Schlüssel widerrufen wurde, Ursprung oder Produkt verlor oder vor einer Tarifherabstufung ausgestellt wurde; ausgesetzte Organisation oder Organisation ohne Tarif.	Schlüsselwert und Status auf der API-Keys-Seite prüfen. Bei einer Sitzung erneut austauschen.
401	publishable_requires_session	Ein veröffentlichbarer Schlüssel wurde an einen Laufzeitendpunkt gesendet.	Gegen eine Sitzung eintauschen oder das Backend mit einem Serverschlüssel aufrufen lassen.
403	publishable_key_required	Der Sitzungsaustausch wurde mit einem Server- oder Legacy-Schlüssel aufgerufen.	Beim Austausch einen Schlüssel mit Präfix kld_pk_… verwenden.
403	origin_required	Beim Sitzungsaustausch fehlt der Origin-Header.	Austausch von einer Browserseite aus durchführen.
403	origin_not_allowed	Der Seitenursprung steht nicht unter den erlaubten Ursprüngen des Schlüssels oder den erlaubten Domains der veröffentlichten Karte.	Den exakten Ursprung zum Schlüssel oder die Domain zur Karte hinzufügen.
403	product_not_allowed	Das angefragte Produkt ist nicht erlaubt: entweder das beim Austausch angeforderte product oder bei Server-/Legacy-Schlüsseln das Produkt des aufgerufenen Endpunkts.	allowed_products ändern oder einen anderen Schlüssel verwenden.
403	insufficient_scope	Der Schlüssel wurde ohne den Scope erstellt, den der Endpunkt oder das Produkt benötigt.	Schlüssel mit diesem Scope verwenden. Scopes sind nicht nachträglich änderbar.
403	tier_capability_not_allowed	Der Schlüssel hat den Scope oder das Produkt, der aktuelle Tarif umfasst es jedoch nicht.	Tarif unter kaleidr.com/billing ändern.
403	server_key_in_browser	Ein Serverschlüssel wurde mit Origin-Header gesendet.	Aufruf ins Backend verlegen. Stand der Schlüssel im Seitenquelltext, ihn rotieren.
403	session_origin_mismatch	Ein Sitzungstoken wurde von einem anderen Ursprung als bei seiner Erstellung verwendet, oder eine Sitzung für veröffentlichte Karten wurde ohne Origin verwendet.	Sitzung auf der Seite austauschen, die sie nutzt.
403	ip_not_allowed	Ein Server-/Legacy-Schlüssel mit IP-Zulassungsliste wurde von einer nicht erlaubten Adresse verwendet.	Erlaubte Adresse verwenden oder allowed_ips ändern.
403	chat_disabled	Austausch für veröffentlichte Karte: Die Kaleidr AI der Karte aktiviert die angeforderte Funktion nicht.	Control Tower oder Popup Window in der Kachel Kaleidr AI der Karte in Studio aktivieren.
403	owner_has_no_organization	Austausch für veröffentlichte Karte: Dem Karteneigentümer fehlt eine Organisation.	Eigentümer muss eine Organisation erstellen oder einer beitreten.
404	not_found	Austausch für veröffentlichte Karte: Keine veröffentlichte Karte und kein Freigabelink mit dieser ID.	ID und Veröffentlichungsstatus prüfen.

Der vollständige Katalog einschließlich 429- und 5xx-Antworten steht unter Fehler.

Verwandte Themen

• Sicherheitsmodell: Was ein kompromittierter Schlüssel ermöglichen kann.
• CORS und erlaubte Ursprünge: Wie die Ursprungsliste durchgesetzt wird.
• Endpunkte: Welche Aufrufe jeder Scope erlaubt.
• API-Schlüssel erhalten: Einen Schlüssel auf der API-Keys-Seite erstellen.