API-Key: Rechte, Gültigkeit, Rotieren

Beim Anlegen eines API-Schlüssels unter Integrationen → API / MCP, Reiter API-Keys, „Neuer Key“ legst du fest, was er darf und wie lange er gilt. Wie du den Schlüssel anlegst und benutzt: siehe Daten-API: Schlüssel, Zugriff und Dokumentation.

Rechte: was der Schlüssel darf

Am Anfang steht alles auf Aus. Gib nur frei, was das Programm wirklich braucht. Ohne irgendein Recht lässt sich kein Schlüssel anlegen. Die Rechte sind in drei Blöcke geteilt:

• Ohne Kundendaten, je Aus, Lesen oder Lesen und schreiben: Buchungen und Kalender (mit Versicherung), Einheiten und Preise (mit Verfügbarkeit), Gästemappen und Webhooks einrichten (ein Programm wie Zapier oder Make legt selbst Webhooks an). Buchungen kommen hier ohne Gastdaten: nur Datum, Einheit, Preis und Anzahl Personen. „Alle lesen“ und „Alle lesen und schreiben“ setzen diesen Block auf einmal.
• Mit Kundendaten, einzeln anzuhaken: „Gastdaten in Buchungen“ (Name, E-Mail, Telefon, Adresse und Ausweisdaten der Gäste; geht nur zusammen mit Buchungen und Kalender), „Nachrichten an Gäste“ (die Unterhaltungen mit deinen Gästen, auch Türcodes, die darin stehen; Lesen oder Lesen und schreiben) und „Rechnungen lesen“.
• Zugang: Türcode, Türlinks, Check-in-Link, WLAN-Passwort und die eigenen Felder der Einheit.

Hakst du etwas aus „Mit Kundendaten“ oder „Zugang“ an, bestätigst du: „Dieser Key gibt Kundendaten oder Zugang zu deinen Wohnungen heraus. Ich bin dafür verantwortlich, ihn sicher aufzubewahren, nicht Xentra.“

Was ohne ein Recht passiert

Jeder Endpunkt prüft sein Recht, auch beim Lesen. Ohne „Gastdaten in Buchungen“ kommen Name, Kontakt- und Ausweisfelder einer Buchung leer (null) zurück, und E-Mail oder Telefon eines Gastes zu setzen beantwortet die API mit 403. Ohne Zugang sind Türcode, Check-in-Link, Gästemappen-Link, WLAN-Passwort und die eigenen Felder der Einheit leer, und die Link-Endpunkte antworten mit 403. Rechnungen brauchen „Rechnungen lesen“, Gästenachrichten „Nachrichten an Gäste“. Die Fehlermeldung nennt das fehlende Recht, zum Beispiel write:bookings oder read:invoices.

Die Rechte eines Schlüssels lassen sich nachträglich nicht ändern; leg dafür einen neuen an. Freigeben lassen sich nur ganze Bereiche, keine einzelnen Endpunkte. Schlüssel, die du vor der Einführung der Rechte angelegt hast, behalten alles, was sie bisher konnten, und laufen ohne Ablaufdatum weiter.

Gültigkeit

Beim Anlegen wählst du 90 Tage, 1 Jahr (empfohlen) oder Läuft nie ab. Unbegrenzt ist nicht empfohlen: ein gestohlener oder vergessener Schlüssel bliebe dauerhaft gültig. 30 und 7 Tage vor dem Ablauf erinnern wir dich per Glocke und E-Mail, dazu einmal, wenn er abgelaufen ist.

In der Liste zeigt die Spalte Rechte Kürzel wie „Buchungen: lesen“, „Gastdaten“ oder „Zugang“. Die Spalte Status zeigt Aktiv mit „bis “ oder „läuft nie ab“ (ab 30 Tagen vor dem Ende orange), Abgelaufen, Ersetzt oder Widerrufen.

Rotieren und Erneuern

• Rotieren (Pfeil-Symbol, „Rotieren: neuer Key, gleiche Rechte“): Nach „Neuen Key erstellen“ bekommst du einen neuen Schlüssel mit denselben Rechten und derselben Laufzeit, der Name wird hochgezählt (aus „Zapier“ wird „Zapier_2“). Trag ihn in deinem Programm ein: der alte funktioniert noch 24 Stunden, danach steht er auf Ersetzt. Jeder Schlüssel lässt sich einmal rotieren.
• Erneuern erscheint bei einem abgelaufenen oder widerrufenen Schlüssel und erstellt einen neuen mit denselben Rechten. Ein widerrufener Schlüssel bleibt für immer gesperrt.

Rotieren und Erneuern brauchen wie das Anlegen ein aktives Abo. Verbindungen mit Claude oder ChatGPT (der Name endet auf „(MCP)“) lassen sich hier nicht rotieren oder erneuern: Um sie zu ändern, entfernst du sie und verbindest den Assistenten neu, siehe Claude oder ChatGPT mit Xentra verbinden (MCP).