Schnittstelle: Anmeldung, Schlüssel und Rechte

Die Schnittstelle unter https://app.xicbot.de/api/v1/ kennt drei Anmeldewege, und jeder öffnet nur seinen eigenen Zweig: die Sitzungsmarke aus der Anmeldung für alles, was die Anwendung selbst tut, den API-Schlüssel für die Anbindung eigener Systeme unter /api/v1/integration/ und den öffentlichen Schlüssel des Chatfensters. Danach entscheiden Status des Kontos, bestätigte E-Mail-Adresse, Rolle, Tarif und Bereich, ob eine Anfrage durchkommt. Diese Seite beschreibt die Stufen der Reihe nach, jeweils mit ihren Ablehnungen.

Drei Anmeldewege im Überblick

Die Wege lassen sich nicht vertauschen. An /api/v1/integration/ zählt nur der Kopf X-Api-Key; eine Sitzungsmarke dort endet mit 401 und key_missing. Umgekehrt ist ein API-Schlüssel keine Sitzungsmarke: im Kopf Authorization an einer Route der Anwendung endet er mit 401. Routen ohne Anmeldung (Anmelden, Statusseite, Anfrageformular, Demo, Rechtstexte, Einladung, Warenkorb) beschreibt Öffentliche Wege.

Es gibt eine Fassung der Schnittstelle, v1, und sie steht im Pfad. Eine Adresse wie /api/v2/… bekommt dieselbe Antwort wie eine erfundene: 404 mit route_unknown. Gibt es den Pfad, aber nicht mit der verwendeten Methode, lautet die Antwort 405 mit method_not_allowed, und allowed listet die Methoden, die der Pfad annimmt. Ein Accept-Kopf ist nicht nötig; unter /api/ antwortet die Schnittstelle in JSON, auch mit 401, wenn die Anmeldung fehlt. Aufbau der Antworten und Fehler: Grundlagen der Schnittstelle.

Sitzungsmarke aus der Anmeldung

POST /api/v1/login mit E-Mail-Adresse und Passwort liefert bei Erfolg token, expires_at und user. Jede Anmeldung bekommt eine eigene Marke mit 30 Tagen Laufzeit. Benannt wird sie nach der Kennung des Browsers oder Programms (User-Agent, höchstens 190 Zeichen), ohne Kennung heißt sie sitzung. Die Marke gehört in jede weitere Anfrage als Authorization: Bearer <Marke>. Die Felder der Anmeldung im Einzelnen stehen unter Öffentliche Wege.

• 422 mit bad_credentials: Adresse oder Passwort stimmen nicht.
• 428 mit totp_required oder webauthn_required: ein zweiter Faktor ist eingerichtet. Die Antwort trägt challenge, expires_in (600 Sekunden) und methods, bei hinterlegtem Sicherheitsschlüssel zusätzlich das Objekt webauthn mit challenge, rp_id, allow und timeout; mehr unter Konto und Sicherheit.
• 422 mit bad_totp: der Code des zweiten Faktors stimmt nicht.
• 422 mit challenge_expired: der Nachweis aus der 428-Antwort gilt nicht mehr, weil die 600 Sekunden abgelaufen sind, weil der zweite Schritt von einer anderen IP-Adresse kommt als der erste oder weil der Nutzer inzwischen keinen zweiten Faktor mehr hat.
• 422 mit bad_webauthn und reason: die Anmeldung mit dem Sicherheitsschlüssel wurde nicht angenommen, reason nennt den Grund. 422 mit webauthn_not_offered: der zweite Aufruf schickt eine Schlüsselunterschrift, obwohl die 428-Antwort kein webauthn in methods hatte. 503 mit webauthn_unconfigured: die Anmeldung mit Sicherheitsschlüssel steht derzeit nicht zur Verfügung.
• 429 mit too_many_attempts und retry_in: zu viele Versuche, siehe Grenzen der Schnittstelle.
• 403 mit tenant_paused, tenant_suspended oder tenant_deleted: das Konto ist nicht aktiv, und der Nutzer gehört keinem weiteren aktiven Konto an; es wird keine Marke ausgegeben. Gehört er einem weiteren aktiven Konto an, meldet ihn die Anmeldung dort an, ein Konto, dessen Inhaber er ist, zuerst, sonst das, dem er am längsten angehört; der Wechsel steht dort im Protokoll mit cause login, eine laufende Übernahme endet. Diese Antwort kommt erst nach richtigen Zugangsdaten und bestandenem zweitem Faktor und trägt, anders als bei späteren Anfragen, kein Feld message.

Mit welchen Rechten eine Marke arbeitet, zeigt GET /api/v1/me. Maßgeblich sind user.role, user.email_verified und user.operator sowie tenant.status, tenant.plan und tenant.features; ohne zugeordnetes Konto ist tenant null. Die Route und alle Felder beschreibt Konto per Schnittstelle.

curl -s https://app.xicbot.de/api/v1/me \
  -H "Authorization: Bearer <Marke>"

Fehlt die Marke, ist sie abgelaufen oder gelöscht, antwortet jede Route mit Anmeldung mit 401. Die Anwendung hält ihre Marke im lokalen Speicher des Browsers; bekommt sie ein 401, beendet sie die Sitzung und zeigt auf der Anmeldeseite Ihre Sitzung ist abgelaufen. Bitte melden Sie sich erneut an. POST /api/v1/logout löscht genau die Marke, mit der es aufgerufen wird. Mit einer Übernahmemarke gilt das als Ende der Übernahme: im Protokoll steht impersonation.end, keine Abmeldung. Anmeldungen auf anderen Geräten bleiben bestehen.

POST /api/v1/invitation/accept nimmt eine Einladung an, solange es zur eingeladenen Adresse noch kein Nutzerkonto gibt; ein gelöschtes Konto zählt dabei nicht mit. Es wird wiederhergestellt und beginnt wie ein neues: mit dem Passwort aus dieser Anfrage, ohne zweite Stufe, ohne Sicherheitsschlüssel und ohne frühere Marken. Dabei setzen Sie ein Passwort mit mindestens 12 Zeichen aus Buchstaben und Ziffern, bestätigt in password_confirmation. Die Antwort kommt mit 201 und einer Marke mit 30 Tagen Laufzeit namens einladung; sie trägt neben token, expires_at und user auch tenant. Ohne Protokolleintrag entstehen weder Konto noch Mitgliedschaft, die Einladung bleibt offen, und die Antwort ist 500 mit not_logged. Gibt es zur Adresse schon ein Nutzerkonto, das nicht gelöscht ist, lautet die Antwort 409 mit login_required und email. Dann melden Sie sich an und nehmen die Einladung mit POST /api/v1/team/invitations/accept an; diese Route verlangt keine bestätigte E-Mail-Adresse, eine noch unbestätigte gilt mit der Annahme als bestätigt. Sie antwortet mit 403 und wrong_account, wenn eine andere Adresse angemeldet ist als die eingeladene. Ohne Protokolleintrag tritt das Konto nicht bei, die Antwort ist dann 500 mit not_logged. Einladen und Rollen vergeben: Team und Rollen.

API-Schlüssel für eigene Systeme

Ein API-Schlüssel gehört zum Konto und öffnet nur /api/v1/integration/. Er besteht aus xbot_ und 48 zufälligen Buchstaben und Ziffern und steht im Kopf X-Api-Key; einen Weg über Authorization: Bearer gibt es für Schlüssel nicht. Die Anwendung sagt dazu Ein Schlüssel wird genau einmal im Klartext angezeigt. Gespeichert wird nur sein Abdruck. Abgelegt werden der SHA-256-Abdruck und die ersten zwölf Zeichen; diese bleiben als Kennung sichtbar, damit sich Schlüssel in der Liste auseinanderhalten lassen.

Die Schnittstelle prüft einen Schlüssel in fester Reihenfolge; die erste zutreffende Stufe antwortet:

Minuten- und Tagesdeckel

Jeder Schlüssel hat einen Minutendeckel aus Anfragen pro Minute und einen Tagesdeckel, dessen Höhe am Konto steht; beide zählen je Schlüssel. Ist einer erreicht, antwortet die Schnittstelle mit 429 und too_many_requests und nennt die Wartezeit in retry_after und im Kopf Retry-After. Werte, Zeitfenster, Zählweise und ein Beispiel der Antwort stehen unter Paketsperren und Drosseln.

Für den ersten Test eines neuen Schlüssels eignet sich GET /api/v1/integration/status: die Route verlangt keinen Bereich, liest keine Daten und nennt Konto, Bereiche und Minutendeckel des Schlüssels. Antwort und Beispiel stehen unter Schnittstelle: Integration.

Bereiche eines Schlüssels

Welche Routen ein Schlüssel erreicht, bestimmen seine Bereiche. Jeder Bereich gilt genau so, wie er heißt: leads.write schließt leads nicht ein. Wer Anfragen anlegen und lesen will, braucht beide. Die Anwendung sagt dazu Schreiben ist ein eigener Bereich. Ohne ihn liest ein Schlüssel nur. Pfade relativ zu /api/v1/integration/:

Fehlt der verlangte Bereich, antwortet die Route mit 403, und required nennt ihn. Endet er auf .write, heißt der Fehler read_only, sonst scope_missing.

Bereiche, Name und Minutendeckel eines Schlüssels lassen sich nach dem Anlegen nicht ändern; eine Route dafür gibt es nicht. Für andere Bereiche legen Sie einen neuen Schlüssel an und ziehen den alten zurück.

API-Schlüssel in der Anwendung verwalten

Angelegt, aufgelistet und zurückgezogen werden Schlüssel auf der Seite Schnittstellen unter https://app.xicbot.de/schnittstellen, ab der Rolle Verwaltung. Anlegen setzt voraus, dass der Tarif das Merkmal enthält; sonst antwortet POST /api/v1/keys mit 402 und plan_feature_missing. Auflisten und Zurückziehen gehen auch ohne das Merkmal, damit sich ein Schlüssel aus der Zeit vor einem Tarifwechsel zurückziehen lässt; benutzen lässt er sich ohne das Merkmal nicht. Die Routen GET /api/v1/keys, POST /api/v1/keys und DELETE /api/v1/keys/{id} verlangen dieselbe Rolle, eine bestätigte E-Mail-Adresse dagegen nicht. Gültig sein können höchstens zehn Schlüssel gleichzeitig, und den Klartext enthält nur die Antwort auf das Anlegen. Felder, Schritte, Liste und Zurückziehen beschreibt Schlüssel und Webhooks; welche Tarife das Merkmal tragen, zeigen Pakete und Kontingente und die Preise.

Öffentlicher Schlüssel des Chatfensters

Jeder Assistent bekommt beim Anlegen einen öffentlichen Schlüssel aus 32 Hexadezimalzeichen. Er steht nicht in einem Kopf, sondern im Pfad: /api/v1/public/widget/{key}/…. Eine Sitzung braucht dieser Zweig nicht. Am Assistenten zeigt die Anwendung ihn unter Öffentlicher Schlüssel mit dem Hinweis Er steht im Klartext auf jeder fremden Seite. Er erlaubt nur, dieses eine Chatfenster zu nutzen.

Vier Fälle antworten gleich, mit 404 und unknown_widget: der Schlüssel ist unbekannt, Chatfenster freigeben ist aus, der Assistent steht nicht auf aktiv (also auf Entwurf oder pausiert), oder das Konto ist nicht aktiv. Von außen ist nicht zu unterscheiden, welcher Fall vorliegt. Ein neuer Assistent hat Chatfenster freigeben ausgeschaltet. Trifft keiner der vier Fälle zu und gehört der Assistent zu einem Demokonto, dessen Frist abgelaufen ist, lautet die Antwort 404 mit demo_expired.

Neuen Schlüssel erzeugen ersetzt den Schlüssel nach der Rückfrage Neuen Schlüssel erzeugen? Der bisherige Einbaucode hört sofort auf zu arbeiten. Danach steht Neuer Schlüssel ist aktiv. Bitte den Einbaucode überall austauschen. Das dürfen die Rollen Verwaltung und Inhaber; die übrigen sehen Einen neuen Schlüssel erzeugt, wer die Rolle Verwaltung oder Inhaber hat. Den Einbaucode beschreibt Widget einbauen, die Routen des Zweigs Schnittstelle des Chatfensters.

Über die Schnittstelle tauscht POST /api/v1/assistants/{id}/key den Schlüssel aus. Bedingungen, Antwort und Fehler der Route stehen unter Schnittstelle: Wissen und Assistenten.

Was eine Route zusätzlich verlangt

Nach dem Anmeldeweg prüft die Schnittstelle je Routengruppe weitere Bedingungen, und zwar bei jeder Anfrage:

Einzelne Routen verlangen darüber hinaus eine Rolle oder ein Tarifmerkmal; das steht bei der Route in Wissen und Assistenten und Gespräche und Verwaltung. Die Ablehnungen der Sitzungsrouten und was die Anwendung dazu anzeigt:

Der Status des Kontos (active, paused, suspended oder deleted) wird bei jeder Anfrage geprüft, nicht nur beim Anmelden. Wird ein Konto pausiert, scheitert also auch eine noch gültige Marke mit 403. Ausgenommen sind POST /api/v1/tenant/switch, damit sich aus einem nicht aktiven Konto heraus in ein anderes wechseln lässt, sowie POST /api/v1/logout und POST /api/v1/impersonation/stop, die nur die eigene Marke beenden. Ohne bestätigte E-Mail-Adresse bleiben die Kontorouten, die Schlüsselverwaltung und impersonation/stop erreichbar, die Fachbereiche nicht; wie Sie die Adresse bestätigen, steht unter Anmelden und Zugang.

Rollen

Eine Route mit Rollenbedingung verlangt mindestens den genannten Rang; höhere Rollen kommen ebenfalls durch. Eine unbekannte eigene Rolle zählt als 0, eine unbekannte verlangte Rolle als 99, beides endet also mit einer Ablehnung: 403 mit role_too_low und required. Einzelne Routen verlangen die Rolle Inhaber, etwa die Datenausfuhr mit GET /api/v1/privacy/export. Was jede Rolle in der Anwendung darf, steht unter Team und Rollen.

Die Rolle hängt am Paar aus Nutzer und Konto. Wer mit POST /api/v1/tenant/switch in ein anderes Konto wechselt, bekommt die Rolle, die er dort hat. Ein Konto, dem der Nutzer nicht angehört, ergibt dieselbe Antwort wie ein unbekanntes: 404 mit not_found. Ist das Ziel nicht aktiv, lautet die Antwort 403 mit tenant_<status> und „Das Konto ist derzeit nicht aktiv.“ Während einer Übernahme ist der Wechsel gesperrt (403, in_impersonation).

Betreiberzugang und Übernahme

Betreiber ist keine Rolle, sondern ein eigenes Merkmal des Nutzers (user.operator). Ein Inhaber ist darum kein Betreiber. Die Routen unter /api/v1/admin/ verlangen dieses Merkmal und eine bestätigte Adresse; ohne Merkmal antworten sie mit 403 und not_operator, während einer Übernahme mit 403 und in_impersonation. In der Navigation steht Betrieb in der Gruppe Betreiber nur für Betreiber und nicht während einer Übernahme.

Zur Fehlersuche kann der Betreiber ein Konto übernehmen, in der Anwendung mit Konto übernehmen und dem Feld Grund der Übernahme, über die Schnittstelle mit POST /api/v1/admin/tenants/{id}/impersonate und optional reason. Der Grund wird nach 200 Zeichen abgeschnitten. Die Übernahme erzeugt eine eigene Marke für den ranghöchsten Nutzer, der gerade in diesem Konto arbeitet, bei gleichem Rang für den am längsten eingetragenen; ein Mitglied, das gerade in einem anderen Konto arbeitet, zählt nicht mit. Sie gilt 4 Stunden, ihr Name beginnt mit impersonation:, und es wird dabei kein Passwort gelesen oder gesetzt. Der Beginn wird mit dem Grund protokolliert, das Ende ohne ihn.

• Die Antwort trägt token, expires_at, user (id, email, name) und tenant (id, name). Ein unbekanntes Konto ergibt 404 mit unknown, ein nicht aktives 409 mit tenant_inactive, ein Konto, in dem gerade niemand arbeitet, 422 mit tenant_without_user.
• Mit der Übernahmemarke liefert GET /api/v1/me unter impersonation die Adresse des Betreibers (operator) und expires_at. Die Anwendung zeigt dann in der Statusleiste Übernahme mit dieser Adresse und dem Knopf Übernahme beenden; ein Vorleseprogramm hört dort Sie arbeiten im Konto eines Kunden.
• Abmelden während einer Übernahme beendet sie wie Übernahme beenden; in der Anwendung ist dann auch der Betreiber in seinem eigenen Konto abgemeldet.
• In der Sitzungsliste unter Konto in Angemeldete Geräte erscheint die Übernahme als Übernahme durch den Betreiber. Alle anderen beenden (DELETE /api/v1/sessions) lässt sie und die API-Schlüssel des Kontos stehen; mit Beenden in ihrer Zeile beendet der Kunde sie (DELETE /api/v1/sessions/{id}).
• Gesperrt mit 403 und in_impersonation sind: Passwort ändern (in der Anwendung Während einer Betreuung lässt sich das Passwort nicht ändern.), alle anderen Sitzungen auf einmal beenden, den zweiten Faktor einrichten, bestätigen oder entfernen, Sicherheitsschlüssel anlegen oder entfernen, das Konto wechseln und die Routen unter /api/v1/admin/. Einzeln beenden (DELETE /api/v1/sessions/{id}) lässt sich aus einer Übernahme nur die Übernahme selbst; jede andere Sitzung ergibt ebenfalls 403 mit in_impersonation.
• Die Minutendeckel je Nutzer, etwa für Assistenten oder das Anlegen von Schlüsseln, gelten während einer Übernahme nicht, weil die Anfragen sonst auf den Zähler des Kunden liefen. Weiter zählt der Deckel für das Annehmen des Vertrags zur Auftragsverarbeitung (POST /api/v1/privacy/dpa).

Hat eine Person das einzige Gerät für die zweite Stufe verloren, kann der Betreiber die zweite Stufe zurücksetzen. In der Anwendung ist unter Betrieb auf der Seite eines Mandanten die Zahl neben Nutzer ein Schalter, der die Personen des Mandanten mit Name, E-Mail-Adresse, Rolle, Zweite Stufe und Aktion aufklappt. Gezählt und aufgeführt werden alle, die dem Mandanten angehören, auch wenn sie gerade in einem anderen Mandanten arbeiten; Rolle ist ihre Rolle in diesem Mandanten. Bei Kundenkonten mit eingerichteter zweiter Stufe steht dort Zweite Stufe zurücksetzen, bei Betreiberkonten Betreiberkonto. Der Knopf öffnet die Frage Code und Sicherheitsschlüssel dieser Person entfernen und alle ihre Sitzungen beenden? mit dem Feld Grund (steht im Betreiberprotokoll) (10 bis 500 Zeichen) und den Knöpfen Zurücksetzen und Abbrechen. Über die Schnittstelle heißt der Weg POST /api/v1/admin/users/{id}/second-factor/reset mit reason. Entfernt werden Code und Sicherheitsschlüssel, alle Sitzungen der Person enden, und die Antwort trägt ok, sessions_ended und mail_queued. Ist mail_queued false, ließ sich die Sicherheitsmeldung an die Kontoadresse nicht einreihen; die Anwendung bittet dann, die Person selbst zu benachrichtigen. Ein Betreiberkonto ergibt 403 mit operator_account, eine Person ohne zweite Stufe 409 mit no_second_factor, eine unbekannte Kennung 404 mit unknown. Kommt die Zeile im Betreiberprotokoll oder im Protokoll des Kontos nicht zustande, bleibt das Zurücksetzen aus, und die Antwort ist 500 mit not_logged.

Häufige Fragen