Schnittstelle: Konto, Sicherheit, Abrechnung und Datenschutz

POST /api/v1/logout

Beendet die Sitzung, mit der Sie die Anfrage stellen: die Marke wird gelöscht und gilt danach nicht mehr. Andere Sitzungen bleiben bestehen. Das gelingt auch, wenn das Konto inzwischen nicht mehr aktiv ist. Mit der Marke einer Übernahme beendet der Aufruf die Übernahme wie POST /api/v1/impersonation/stop; im Protokoll steht dann impersonation.end. Die Antwort lautet {"logged_out": true}.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/me

Liefert die angemeldete Person in user, das Konto, in dem sie gerade arbeitet, in tenant und alle Konten, zu denen sie gehört, in tenants. Während einer Übernahme stehen in impersonation die Adresse der übernehmenden Person (operator) und das Ende der Übernahme (expires_at), sonst null.

Anmeldung

Sitzungsmarke, jede Rolle

POST /api/v1/tenant/switch

Wechselt in ein anderes Konto, zu dem Sie gehören, in der Anwendung über Konto wechseln. Im Feld tenant steht die Kennung des Zielkontos (Pflicht, höchstens 64 Zeichen). Sie arbeiten danach mit der Rolle, die Sie in diesem Konto haben. Der Wechsel ist auch möglich, wenn das bisherige Konto nicht aktiv ist; das Ziel muss aktiv sein. Die Antwort enthält user, tenant und tenants wie bei GET /api/v1/me.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

Begrenzung

20 je Minute

PUT /api/v1/tenant/name

Ändert den Namen des Kontos, den Firmen- oder Projektnamen aus der Registrierung; in der Anwendung unter Konto in der Karte Name des Kontos. Im Feld name steht der neue Name (Pflicht, höchstens 160 Zeichen, Leerzeichen am Rand fallen weg). Die Kennung des Kontos (slug) bleibt unverändert. Ändert sich der Name, steht das im Protokoll mit altem und neuem Namen. Die Antwort enthält tenant mit id und name.

Anmeldung

Sitzungsmarke, Rolle Inhaber, bestätigte E-Mail-Adresse, nicht aus einer Übernahme

POST /api/v1/confirmation/resend

Schickt den Bestätigungslink für die E-Mail-Adresse erneut, in der Sprache aus locale; in der Anwendung heißt das Nachricht erneut schicken. Der Endpunkt verlangt keine bestätigte Adresse, sonst wäre er für unbestätigte Konten unerreichbar. Ist die Adresse schon bestätigt, geht nichts hinaus und die Antwort lautet {"confirmed": true, "sent": false}. Sonst verlieren frühere, noch nicht benutzte Links ihre Gültigkeit, der neue gilt 48 Stunden, und die Antwort lautet {"confirmed": false, "sent": true}.

Anmeldung

Sitzungsmarke, jede Rolle

Begrenzung

3 je Minute

PUT /api/v1/password

Ändert das Passwort, in der Anwendung unter Konto mit Passwort ändern. Mit dem Ändern enden alle anderen Anmeldesitzungen der Person; die Sitzung, aus der die Anfrage kommt, und eine laufende Übernahme durch den Betreiber bleiben bestehen. API-Schlüssel sind keine Sitzungen und bleiben gültig. Danach geht eine Mail an die Adresse des Kontos, die Zeitpunkt und Zahl der beendeten Sitzungen nennt.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

Begrenzung

5 je Minute, gemeinsam mit dem Abschalten der zweiten Stufe und dem Entfernen von Schlüsseln

POST /api/v1/totp

Erzeugt ein neues Geheimnis aus 20 Zufallsbytes und liefert es Base32-kodiert in secret sowie als otpauth://-Adresse in url für die Authentifizierungs-App: Verfahren nach RFC 6238, Aussteller XICBOT, SHA1, sechs Ziffern, 30 Sekunden je Code. In der Anwendung steht der Wert unter Geheimnis. Ein erneuter Aufruf ersetzt ein noch nicht bestätigtes Geheimnis. Ist die zweite Stufe schon aktiv, antwortet der Endpunkt mit 409 totp_already_active.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

POST /api/v1/totp/confirm

Bestätigt das Geheimnis mit einem Code im Feld totp (Pflicht, höchstens 10 Zeichen; in der Anwendung Sechsstelliger Code). Leerzeichen werden entfernt, danach müssen genau sechs Ziffern übrig bleiben. Angenommen wird der Code des laufenden 30-Sekunden-Abschnitts und der des vorigen und des folgenden. Die Antwort lautet {"is_active": true}. Ohne Protokolleintrag wird die zweite Stufe nicht eingeschaltet, die Antwort ist dann 500 mit not_logged.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

DELETE /api/v1/totp

Schaltet die zweite Stufe ab (Abschalten) und verlangt dafür das Passwort im Feld password des Anfragekörpers. Geheimnis und Bestätigung werden gelöscht. Die Antwort lautet {"is_active": false}. Ohne Protokolleintrag bleibt die zweite Stufe eingeschaltet, die Antwort ist dann 500 mit not_logged.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

Begrenzung

5 je Minute, gemeinsam mit Passwortänderung und Entfernen von Schlüsseln

GET /api/v1/webauthn

Listet die hinterlegten Schlüssel der angemeldeten Person in keys, die ältesten zuerst.

Anmeldung

Sitzungsmarke, jede Rolle

POST /api/v1/webauthn/options

Erzeugt eine Aufforderung aus 32 Zufallsbytes und merkt sie sich für die angemeldete Person; je Person gilt nur die zuletzt geholte. Die Antwort enthält, was der Browser für navigator.credentials.create braucht.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

POST /api/v1/webauthn

Reicht das Ergebnis von navigator.credentials.create ein. Der Server prüft Aufforderung, Herkunft der Seite und Unterschrift selbst. Nach einer erfolgreichen Prüfung ist die Aufforderung verbraucht; für einen weiteren Versuch holen Sie eine neue. Die Antwort (201) enthält den neuen Schlüssel in key und die ganze Liste in keys. Ohne Protokolleintrag wird der Schlüssel nicht gespeichert, die Antwort ist dann 500 mit not_logged.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

DELETE /api/v1/webauthn/{id}

Entfernt einen Schlüssel (Entfernen) und verlangt dafür das Passwort im Feld password des Anfragekörpers, wie das Abschalten der Codestufe. Die Antwort enthält die verbliebenen Schlüssel in keys. Ohne Protokolleintrag bleibt der Schlüssel bestehen, die Antwort ist dann 500 mit not_logged.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

Begrenzung

5 je Minute, gemeinsam mit Passwortänderung und Abschalten der zweiten Stufe

GET /api/v1/sessions

Listet in sessions die noch gültigen Sitzungen der angemeldeten Person, in der Anwendung Angemeldete Geräte, höchstens 50, die zuletzt benutzten zuerst. Abgelaufene Sitzungen fehlen.

Anmeldung

Sitzungsmarke, jede Rolle

DELETE /api/v1/sessions

Beendet alle anderen Sitzungen der angemeldeten Person (Alle anderen beenden). Die Sitzung, aus der die Anfrage kommt, und Übernahmen durch den Betreiber bleiben bestehen, API-Schlüssel ebenso. Die Antwort nennt in ended die Zahl der beendeten Sitzungen und in kept die Zahl der stehen gebliebenen: support für Übernahmen, die noch laufen (abgelaufene zählen nicht mit), api_keys für die gültigen API-Schlüssel des Kontos. Der Protokolleintrag account.sessions_ended nennt dieselben Zahlen in count, kept_support und kept_api_keys.

Anmeldung

Sitzungsmarke, nicht aus einer Übernahme

DELETE /api/v1/sessions/{id}

Beendet eine einzelne eigene Sitzung (Beenden). Eine Kennung, die nicht zu einer laufenden Sitzung der angemeldeten Person gehört, ergibt 404 not_found, auch die einer schon abgelaufenen. Aus einer Übernahme durch den Betreiber lässt sich nur die Übernahme selbst beenden, jede andere Sitzung ergibt 403 in_impersonation. Die Antwort lautet {"ended": true}.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/logins

Liefert in logins die 50 jüngsten Anmeldeversuche für die angemeldete Person, in der Anwendung Letzte Anmeldungen, gescheiterte eingeschlossen. Jeder Eintrag hat time, result und in device die Browserkennung, auf 240 Zeichen gekürzt. Die IP-Adresse wird nur als Prüfwert gespeichert und nicht ausgegeben.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/billing

Liefert Verbrauch und Positionen des laufenden Monats für das aktuelle Konto, in der Anwendung unter Abrechnung auf der Seite Verbrauch und Abrechnung. Beträge stehen in Cent, netto. Preise der Pakete stehen unter Preise, die Kontingente unter Pakete und Kontingente.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/billing/history

Liefert in months den Verbrauch je Monat, in der Anwendung Verlauf, höchstens 24 Monate, der jüngste zuerst. Jeder Eintrag hat month, tokens_in, tokens_out, die Summe beider in token und die Zahl der Antworten in messages.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/privacy/overview

Liefert den Überblick, den die Anwendung unter Gespeicherte Daten und in den Abschnitten darunter zeigt.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/privacy/legal

Liefert die Anlage Technische und organisatorische Maßnahmen in tom, mit ihrer Fassung in version, der Vertragsfassung in contract_version und den Gruppen in groups; jede Gruppe hat key, title und Punkte mit key, title, text und state. In accessibility steht die Erklärung zur Barrierefreiheit.

Anmeldung

Sitzungsmarke, jede Rolle

GET /api/v1/privacy/export

Liefert die Daten des Kontos als JSON-Datei, in der Anwendung unter Datenexport mit Daten exportieren. Der Export enthält Gespräche im Klartext und steht darum nur dem Inhaber zu. Die Datei heißt xicbot-ausfuhr-<Kontokennung>-<Datum>.json. Lässt sich der Export nicht protokollieren, wird keine Datei ausgeliefert, und die Antwort ist 500 mit not_logged.

Anmeldung

Sitzungsmarke, Rolle Inhaber

Begrenzung

5 je Minute, gemeinsam mit den übrigen ändernden Datenschutz-Endpunkten

GET /api/v1/privacy/export/attachments

Liefert die Dateien, die Besucher angehängt haben, als ZIP-Archiv: je Datei <Gespräch>/<Kennung>.<Endung> und dazu manifest.json mit Kennung, Gespräch, Anfrage, Name, Art, Größe und Prüfsumme, eine fehlende Datei mit missing: true. Die Kopfzeilen x-files und x-files-missing nennen die Zahlen. Lässt sich der Abruf nicht protokollieren, wird nichts ausgeliefert, und die Antwort ist 500 mit not_logged.

Anmeldung

Sitzungsmarke, Rolle Inhaber

Begrenzung

5 je Minute, gemeinsam mit den übrigen ändernden Datenschutz-Endpunkten

PUT /api/v1/privacy/retention

Setzt die Fristen je Objektart in Tagen, in der Anwendung unter Aufbewahrungsfristen mit Speichern. Jedes Feld ist optional: ein fehlendes Feld lässt die Frist unverändert, null setzt sie auf „es wird nichts gelöscht“. Erlaubt sind ganze Zahlen von 1 bis 3650; 0 ist nicht zulässig, weil es etwas anderes bedeutet als null. Die Antwort enthält den neuen Stand in retention_objects. Ohne Protokolleintrag bleiben die bisherigen Fristen stehen, die Antwort ist dann 500 mit not_logged. Was die Fristen bewirken, beschreibt Aufbewahrung und Löschung.

Anmeldung

Sitzungsmarke, ab Rolle Verwaltung

Begrenzung

5 je Minute, gemeinsam mit den übrigen ändernden Datenschutz-Endpunkten

GET /api/v1/privacy/dpa

Liefert den Stand der Auftragsverarbeitung: die geltende Vertragsfassung in contract_version, den Vertragstext in contract, die Annahme in accepted_at, accepted_version und accepted_by (Name der annehmenden Person; accepted_by_gone ist true, wenn sie nicht mehr auffindbar ist) und in contract_pending, ob eine Annahme der geltenden Fassung aussteht. In subprocessors stehen die aktuelle Fassung der Liste (version), die bestätigte Fassung (confirmed_version), ob eine Bestätigung aussteht (change_pending), und das Verzeichnis (directory).

Anmeldung

Sitzungsmarke, jede Rolle

POST /api/v1/privacy/dpa

Nimmt den Vertrag an (Auftragsverarbeitung annehmen) und bestätigt den Stand der Liste (Stand bestätigen). Beide Felder müssen im Anfragekörper stehen: contract als true oder false, subprocessor_version als Fassung der Liste (höchstens 20 Zeichen) oder null. Mit contract: true wird die geltende Fassung mit Zeitpunkt und Person gespeichert, wenn noch keine Annahme besteht oder eine andere als die geltende Fassung angenommen ist; die bisherige Annahme wird dann ersetzt. Ist die geltende Fassung bereits angenommen, bleibt diese Annahme bei einer erneuten Annahme unverändert. Eine Fassung in subprocessor_version wird nur angenommen, wenn sie der aktuellen entspricht. Die Antwort entspricht GET /api/v1/privacy/dpa. Ohne Protokolleintrag werden weder Annahme noch Listenstand gespeichert, die Antwort ist dann 500 mit not_logged.

Anmeldung

Sitzungsmarke, Rolle Inhaber

Begrenzung

10 je Minute je Konto und Person

POST /api/v1/privacy/subprocessors/object

Legt Widerspruch gegen die aktuelle Fassung der Liste der Unterauftragsverarbeiter ein (Widerspruch einlegen). Im Feld reason steht der Grund (Pflicht, 5 bis 1000 Zeichen; in der Anwendung Grund des Widerspruchs). Die Antwort nennt in version die Fassung, gegen die widersprochen wurde, trägt ingested mit true und in objection den festgehaltenen Widerspruch mit id, version, created_at und answered_at. Er steht als eigener Datensatz, verfällt nicht mit der Frist des Protokolls und geht in den Export (subprocessor_objections); der Betreiber erhält eine Meldung mit Konto, Stand und Grund. Kommt die Zeile im Protokoll nicht zustande, wird auch der Datensatz nicht angelegt: die Antwort ist dann 500 mit not_logged, und die Anwendung zeigt Nicht gespeichert: Der Eintrag ins Protokoll kam nicht zustande. Bitte versuchen Sie es erneut. und lässt den Grund im Feld stehen. Ihr Widerspruch ist aufgenommen. Wir melden uns dazu. erscheint nur nach einer Antwort mit ingested true.

Anmeldung

Sitzungsmarke, ab Rolle Verwaltung

Begrenzung

5 je Minute, gemeinsam mit den übrigen ändernden Datenschutz-Endpunkten

POST /api/v1/privacy/deletion

Löscht das aktuelle Konto, in der Anwendung unter Konto löschen. Im Feld confirmation (Pflicht, höchstens 40 Zeichen) steht das Wort aus deletion_word des Überblicks, derzeit LOESCHEN; die Anwendung fragt es mit Zum Bestätigen dieses Wort eingeben ab. Die Löschung arbeitet nach dem Datenkatalog und beginnt nicht, solange catalog.complete nicht auf true steht.

Anmeldung

Sitzungsmarke, Rolle Inhaber

Begrenzung

5 je Minute, gemeinsam mit den übrigen ändernden Datenschutz-Endpunkten