{ "openapi": "3.1.0", "info": { "title": "Datenbriefkasten API", "version": "1.0.0", "description": "Der Datenbriefkasten ist ein Briefkasten für Nachrichten zwischen den Systemen einer Organisation (Hub), ihrer Mandanten und deren Teams (Speichern und Weiterleiten). Ein Teilnehmer legt eine Nachricht ein, der Empfänger holt sie ab und quittiert sie, danach löscht der Dienst sie. Alle Aufrufe gehen per HTTPS von den Teilnehmern aus; der Dienst ruft nie zurück.\n\n## Schlüssel\n\nJeder Aufruf (außer `POST /enroll` und dieser Beschreibung) braucht einen Schlüssel im Header `Authorization: Bearer `. Schlüssel beginnen mit `dbk_`. Es gibt zwei Arten:\n\n- **Teilnehmerschlüssel** (Sicherheitsschema `participantKey`): gehört einem Teilnehmer (Hub, Mandant oder Team). Gilt für `/ping`, `/messages`, `/me/…` und die öffentlichen Schlüssel der Partner. Ein Mandant oder Team bekommt ihn mit `POST /enroll` gegen einen Anmeldecode; jedes Gerät meldet sich mit einem eigenen Code an und hat so einen eigenen Schlüssel, der einzeln gesperrt werden kann.\n- **Organisationsschlüssel** (Sicherheitsschema `organisationKey`): gehört der Organisation und gilt nur für die Verwaltung der Mandanten und Teams (`/participants`, außer `/participants/{slug}/public-key`). Berlin Bird stellt ihn aus.\n\nEin Schlüssel der falschen Art wird wie ein fehlender abgewiesen (`401 unauthenticated`). Schlüssel nie in Protokolle, Beispiele oder Tickets schreiben.\n\n## Ablauf einer Nachricht\n\n1. Senden: `POST /messages` mit einer selbst erzeugten UUID als `id`, dem Empfänger `to` (Kennung, z. B. `gtm-v`), einem frei wählbaren `type` und dem Inhalt `payload` als Base64. Der Inhalt sollte Ende-zu-Ende verschlüsselt sein; der Dienst sieht ihn nie im Klartext an, speichert ihn aber zusätzlich verschlüsselt.\n2. Abholen: `GET /messages` liefert die wartenden Nachrichten (ohne Inhalt), älteste zuerst; `GET /messages/{id}` liefert eine Nachricht mit Inhalt.\n3. Quittieren: `POST /messages/{id}/ack`, erst nachdem die Nachricht sicher gespeichert ist. Danach sind Inhalt und Umschlag gelöscht und die Nachricht ist nicht mehr abrufbar; nur ein Prüfwert der `id` bleibt für die Erkennung von Wiederholungen bis zum Ende der Aufbewahrungsfrist.\n\nGesendet werden kann nur über freigegebene Routen: Hub → Mandant und Mandant → Hub sowie Team → Heimatsystem und Heimatsystem → Team. Das Heimatsystem (`home`) eines Teams ist der Hub oder ein Mandant; ein Team tauscht nur mit ihm Nachrichten aus, nie mit anderen Teams, anderen Mandanten oder (bei einem Team eines Mandanten) dem Hub. Nachrichten des Dienstes kommen vom Absender `system` (z. B. `type` `system.expired` oder `system.participant_removed`, `payload` ist dann unverschlüsseltes JSON) und werden genauso abgeholt und quittiert.\n\n## Wiederholen (gleiche id)\n\nBei einem Netzwerkfehler, einem Timeout oder `5xx` wird `POST /messages` **mit derselben `id`** wiederholt. Kennt der Dienst die `id` dieses Absenders schon, speichert er nichts erneut und antwortet `200` mit dem Umschlag der vorhandenen Nachricht (sonst `201`). So entsteht nie eine doppelte Nachricht. Eine neue Nachricht bekommt immer eine neue UUID. Ist dieselbe `id` beim Empfänger bereits von einem anderen Absender vergeben, kommt `422 validation_failed`. Die `id` bleibt nach dem Quittieren für die Aufbewahrungsfrist gesperrt; nach Ablauf einer Nachricht ist sie wieder frei. Abholen und Quittieren dürfen jederzeit wiederholt werden. Ein wiederholtes Quittieren einer bereits quittierten Nachricht ergibt `404 not_found`; das ist als Erfolg zu werten (die Nachricht ist gelöscht).\n\n## Limits\n\n- **Größe:** Der Inhalt einer Nachricht (nach dem Base64-Dekodieren) darf höchstens so groß sein wie das Limit der Organisation, Standard **5242880 Bytes (5 MiB)**. Darüber: `413 payload_too_large`.\n- **Aufrufe:** höchstens das Limit der Organisation je Minute (Standard **60**): mit Teilnehmerschlüsseln je Teilnehmer (alle seine Schlüssel zusammen), mit dem Organisationsschlüssel je Organisation. Diese Beschreibung (`/openapi.json`, `/openapi.yaml`) höchstens 60 Abrufe je IP-Adresse und Minute. Darüber: `429 too_many_requests` mit dem Header `Retry-After` (Sekunden).\n- **Anmeldung:** höchstens 10 fehlgeschlagene Versuche je IP-Adresse und 100 insgesamt in 60 Minuten, danach `429` bis zum Ende des Zeitfensters, dann auch für gültige Codes. Erfolgreiche Anmeldungen zählen nicht mit.\n- **Liste:** `GET /messages` liefert standardmäßig 50, höchstens 200 Nachrichten je Aufruf.\n- **Typ:** höchstens 100 Zeichen. **Öffentlicher Schlüssel:** höchstens 16384 Zeichen. **Kennungen (slug):** höchstens 64 Zeichen, Kleinbuchstaben, Ziffern und einzelne Bindestriche.\n\n## Aufbewahrung\n\nEine Nachricht, die nicht innerhalb der Aufbewahrungsfrist der Organisation (Standard **14 Tage**) quittiert wird, wird gelöscht; der Absender bekommt eine Systemnachricht `system.expired`. Wartet eine Nachricht länger als die Warnschwelle (Standard 120 Minuten), bekommt die Organisation eine Warnung per E-Mail. Jeder Aufruf wird ohne Inhalte, Typen und Schlüssel protokolliert.\n\n## Schlüsseltausch\n\n`POST /me/keys/rotate` gibt einen neuen Teilnehmerschlüssel aus; der bisherige gilt noch 24 Stunden. Den neuen Schlüssel sofort speichern und mit `GET /ping` prüfen.\n\n## Browser und lokale Dateien (CORS)\n\nDie API erlaubt Aufrufe aus dem Browser von jeder Herkunft (auch aus einer lokal geöffneten HTML-Datei, z. B. einer verschlüsselten Fallakte) mit den Headern `Authorization` und `Content-Type`. Das ist sicher, weil jeder Aufruf einen Schlüssel im Header `Authorization` braucht und die API keine Cookies verwendet: Eine fremde Website kann ohne den Schlüssel nichts abrufen.\n\n## Formate und Fehler\n\nAnfragen und Antworten sind JSON (`Content-Type: application/json`, `Accept: application/json`). Zeitpunkte sind UTC im Format `2026-11-13T09:00:00Z`. Jeder Fehler hat die Form `{\"error\": {\"code\": \"…\", \"message\": \"…\"}}`; Programme werten `code` aus, `message` ist ein deutscher Text für Menschen. Neben den je Operation genannten Codes kann jede Operation `404 not_found` (unbekannter Pfad), `405 method_not_allowed` und `server_error` liefern (`500`, bei Wartung auch `503`). Bei `5xx` später mit denselben Daten wiederholen.", "contact": { "name": "Berlin Bird", "url": "https://berlin-bird.com" } }, "servers": [ { "url": "https://bk.berlin-bird.com/api/v1", "description": "API v1" } ], "tags": [ { "name": "Nachrichten", "description": "Nachrichten senden, abholen und quittieren (Teilnehmerschlüssel)." }, { "name": "Schlüssel", "description": "Eigene Schlüssel und öffentliche Schlüssel der Partner (Teilnehmerschlüssel)." }, { "name": "Anmeldung", "description": "Ein Mandant tauscht seinen Anmeldecode gegen seinen Teilnehmerschlüssel (ohne Schlüssel)." }, { "name": "Verwaltung", "description": "Die Organisation verwaltet ihre Mandanten (Organisationsschlüssel)." }, { "name": "Dokumentation", "description": "Diese Beschreibung der API (ohne Schlüssel)." } ], "paths": { "/ping": { "get": { "operationId": "ping", "tags": [ "Nachrichten" ], "summary": "Verbindung prüfen", "description": "Prüft Schlüssel und Verbindung und nennt den eigenen Teilnehmer, seine Organisation und die Uhrzeit des Dienstes.", "security": [ { "participantKey": [] } ], "responses": { "200": { "description": "Der Schlüssel ist gültig.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "example": { "participant": "gbm-v", "organisation": "gtm-v", "time": "2026-11-13T09:00:00Z" } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/messages": { "post": { "operationId": "sendMessage", "tags": [ "Nachrichten" ], "summary": "Nachricht senden", "description": "Legt eine Nachricht für den Empfänger `to` ein. Absender ist immer der Teilnehmer des Schlüssels (ein `from` im Body wird ignoriert). Wiederholen immer mit derselben `id`: Ist sie von diesem Absender schon bekannt, wird nichts erneut gespeichert und die Antwort ist `200` statt `201`.", "security": [ { "participantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewMessage" }, "example": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "to": "gtm-v", "type": "spende.meldung", "payload": "QkVJU1BJRUw6IGhpZXIgc3RlaHQgZGVyIHZlcnNjaGzDvHNzZWx0ZSBJbmhhbHQgZGVyIE5hY2hyaWNodA==" } } } }, "responses": { "201": { "description": "Die Nachricht wurde eingelegt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" }, "example": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "from": "gbm-v", "to": "gtm-v", "type": "spende.meldung", "created": "2026-11-13T09:00:00Z", "size": 512 } } } }, "200": { "description": "Wiederholung: Die Nachricht mit dieser `id` war schon eingelegt; es wurde nichts erneut gespeichert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" }, "example": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "from": "gbm-v", "to": "gtm-v", "type": "spende.meldung", "created": "2026-11-13T09:00:00Z", "size": 512 } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `route_not_allowed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "route_not_allowed" ] } } } } } ] }, "examples": { "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": { "code": "route_not_allowed", "message": "Diese Route ist nicht freigegeben." } } } } } } }, "404": { "description": "Fehler: `unknown_recipient`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unknown_recipient" ] } } } } } ] }, "examples": { "unknown_recipient": { "summary": "unknown_recipient", "value": { "error": { "code": "unknown_recipient", "message": "Diesen Empfänger gibt es nicht." } } } } } } }, "413": { "description": "Fehler: `payload_too_large`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } } } } } ] }, "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "code": "payload_too_large", "message": "Die Nachricht ist größer als das Limit der Organisation (5242880 Bytes)." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } }, "validation_failed_id": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Diese id ist beim Empfänger bereits vergeben. Bitte eine neue UUID verwenden." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } }, "get": { "operationId": "listMessages", "tags": [ "Nachrichten" ], "summary": "Wartende Nachrichten auflisten", "description": "Liefert die Umschläge der Nachrichten, die auf den eigenen Teilnehmer warten, älteste zuerst, ohne Inhalt. Ist `more` `true`, warten weitere: die gelieferten abholen und quittieren, dann erneut auflisten (es gibt keinen Blätter-Cursor).", "security": [ { "participantKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der gelieferten Nachrichten.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 20 } ], "responses": { "200": { "description": "Die wartenden Nachrichten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" }, "example": { "messages": [ { "id": "3f2b8c1e-6a4d-4e7b-9c2a-5d8e1f0a7b3c", "from": "gtm-v", "to": "gbm-v", "type": "spende.meldung", "created": "2026-11-13T09:00:00Z", "size": 2048 } ], "more": false } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/messages/{id}": { "get": { "operationId": "getMessage", "tags": [ "Nachrichten" ], "summary": "Nachricht abholen", "description": "Liefert eine wartende Nachricht des eigenen Teilnehmers mit Inhalt (`payload`, Base64). Die Nachricht bleibt bis zur Quittung liegen; Abholen darf wiederholt werden.", "security": [ { "participantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Die `id` (UUID) der Nachricht.", "schema": { "type": "string", "format": "uuid" }, "example": "3f2b8c1e-6a4d-4e7b-9c2a-5d8e1f0a7b3c" } ], "responses": { "200": { "description": "Die Nachricht mit Inhalt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "3f2b8c1e-6a4d-4e7b-9c2a-5d8e1f0a7b3c", "from": "gtm-v", "to": "gbm-v", "type": "spende.meldung", "created": "2026-11-13T09:00:00Z", "size": 2048, "payload": "QkVJU1BJRUw6IHZlcnNjaGzDvHNzZWx0ZXIgSW5oYWx0" } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Die Nachricht ist unbekannt, bereits quittiert oder nicht für diesen Teilnehmer bestimmt." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/messages/{id}/ack": { "post": { "operationId": "acknowledgeMessage", "tags": [ "Nachrichten" ], "summary": "Nachricht quittieren", "description": "Bestätigt den Empfang. Inhalt und Umschlag werden sofort gelöscht; die Nachricht ist danach nicht mehr abrufbar (`404`). Erst quittieren, wenn die Nachricht sicher gespeichert ist.", "security": [ { "participantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Die `id` (UUID) der Nachricht.", "schema": { "type": "string", "format": "uuid" }, "example": "3f2b8c1e-6a4d-4e7b-9c2a-5d8e1f0a7b3c" } ], "responses": { "204": { "description": "Quittiert und gelöscht." }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Die Nachricht ist unbekannt, bereits quittiert oder nicht für diesen Teilnehmer bestimmt." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/me/public-key": { "put": { "operationId": "updateOwnPublicKey", "tags": [ "Schlüssel" ], "summary": "Eigenen öffentlichen Schlüssel veröffentlichen", "description": "Veröffentlicht oder ersetzt den öffentlichen Schlüssel des eigenen Teilnehmers, mit dem die Partner Nachrichten an ihn verschlüsseln. Der Text ist für den Dienst undurchsichtig (z. B. PEM); nie den privaten Schlüssel senden.", "security": [ { "participantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyUpdate" }, "example": { "public_key": "-----BEGIN PUBLIC KEY-----\nBEISPIEL-NICHT-ECHT\n-----END PUBLIC KEY-----" } } } }, "responses": { "200": { "description": "Der veröffentlichte Schlüssel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKey" }, "example": { "participant": "gbm-v", "public_key": "-----BEGIN PUBLIC KEY-----\nBEISPIEL-NICHT-ECHT\n-----END PUBLIC KEY-----", "fingerprint": "SHA256:82d4a5786f819785c92567f0df5aba0119b581292defda4de79b81f38d689a2e", "updated_at": "2026-11-13T09:00:00Z" } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/me/keys/rotate": { "post": { "operationId": "rotateOwnKey", "tags": [ "Schlüssel" ], "summary": "Teilnehmerschlüssel tauschen", "description": "Gibt einen neuen Teilnehmerschlüssel aus. Ohne Body (oder mit `\"immediate\": false`) gilt der Schlüssel dieses Aufrufs noch bis `previous_key_expires_at` (Standard 24 Stunden) und läuft dann ab: Den neuen Schlüssel sofort speichern, mit `GET /ping` prüfen und erst dann den alten löschen. **Bei Verdacht auf ein Leck** `\"immediate\": true` senden: Sofort ungültig wird die ganze Tauschkette dieses Schlüssels (`previous_key_expires_at` = Zeitpunkt des Aufrufs): der Schlüssel dieses Aufrufs, jeder daraus (auch über mehrere Täusche) getauschte Schlüssel, z. B. der eines Angreifers, und jeder Vorgänger, der noch in der Übergangszeit ist, samt den anderen daraus getauschten Schlüsseln. Schlüssel anderer Ketten bleiben gültig: weitere Geräte (eigener Anmeldecode) und mit `dbk:token:create` ausgestellte Schlüssel, auch mit Ablaufdatum. Vor Einführung der Tauschkette getauschte Schlüssel bilden je eine eigene Kette. Gilt auch für das eigene System (Hub). Den neuen Schlüssel dann unbedingt speichern, bevor die Antwort verworfen wird: Geht sie verloren, hilft nur noch ein neuer Anmeldecode (Mandant/Team: von der Organisation, Hub: von Berlin Bird Studios).", "security": [ { "participantKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotation" }, "example": { "immediate": true } } } }, "responses": { "201": { "description": "Der neue Schlüssel. Er wird nur dieses eine Mal gezeigt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedKey" }, "example": { "participant_key": "dbk_BEISPIELSCHLUESSEL_NICHT_ECHT_0000000000000000", "previous_key_expires_at": "2026-11-14T09:00:00Z" } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/public-key": { "get": { "operationId": "getPublicKey", "tags": [ "Schlüssel" ], "summary": "Öffentlichen Schlüssel eines Partners lesen", "description": "Liefert den öffentlichen Schlüssel eines Teilnehmers, zu dem eine Route besteht (oder den eigenen). `public_key` ist `null`, solange keiner veröffentlicht ist. Ändert sich `fingerprint`, hat der Partner einen neuen Schlüssel.", "security": [ { "participantKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers, dessen öffentlicher Schlüssel gelesen wird.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gtm-v" } ], "responses": { "200": { "description": "Der öffentliche Schlüssel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKey" }, "example": { "participant": "gtm-v", "public_key": "-----BEGIN PUBLIC KEY-----\nBEISPIEL-NICHT-ECHT\n-----END PUBLIC KEY-----", "fingerprint": "SHA256:82d4a5786f819785c92567f0df5aba0119b581292defda4de79b81f38d689a2e", "updated_at": "2026-11-13T09:00:00Z" } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/enroll": { "post": { "operationId": "enroll", "tags": [ "Anmeldung" ], "summary": "Mandant oder Team anmelden", "description": "Tauscht den einmaligen Anmeldecode gegen einen eigenen Teilnehmerschlüssel. Der Mandant oder das Team ist danach `active`. `hub` nennt das System, an das Nachrichten gehen: bei einem Mandanten den Hub, bei einem Team sein Heimatsystem (`home`). Jede weitere Anmeldung mit einem neuen Code (z. B. eines weiteren Geräts) gibt einen zusätzlichen Schlüssel aus; `label` benennt ihn (z. B. den Gerätenamen). Optional wird gleich der eigene öffentliche Schlüssel veröffentlicht. Bindestriche, Leerzeichen sowie Groß- und Kleinschreibung im Code sind egal.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentRequest" }, "example": { "code": "ABCDE-FGHJK-MNPQR", "label": "Laptop Empfang", "public_key": "-----BEGIN PUBLIC KEY-----\nBEISPIEL-NICHT-ECHT\n-----END PUBLIC KEY-----" } } } }, "responses": { "201": { "description": "Angemeldet. Den Teilnehmerschlüssel sofort sicher speichern; er wird nur dieses eine Mal gezeigt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResult" }, "example": { "participant": "neu-v", "organisation": "gtm-v", "hub": "gtm-v", "kind": "mandant", "home": null, "participant_key": "dbk_BEISPIELSCHLUESSEL_NICHT_ECHT_0000000000000000", "public_key": { "participant": "neu-v", "public_key": "-----BEGIN PUBLIC KEY-----\nBEISPIEL-NICHT-ECHT\n-----END PUBLIC KEY-----", "fingerprint": "SHA256:82d4a5786f819785c92567f0df5aba0119b581292defda4de79b81f38d689a2e", "updated_at": "2026-11-13T09:00:00Z" } } } } }, "410": { "description": "Fehler: `enrollment_code_invalid`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "enrollment_code_invalid" ] } } } } } ] }, "examples": { "enrollment_code_invalid": { "summary": "enrollment_code_invalid", "value": { "error": { "code": "enrollment_code_invalid", "message": "Der Anmeldecode ist ungültig, abgelaufen oder bereits verwendet. Bitte bei der Organisation einen neuen Code anfordern." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants": { "get": { "operationId": "listParticipants", "tags": [ "Verwaltung" ], "summary": "Teilnehmer auflisten", "description": "Hub, Mandanten und Teams der eigenen Organisation, Hub zuerst, dann nach `slug`. Mit `kind` und `home` gefiltert, z. B. `?kind=team&home=gbm-v` für die Teams des Mandanten `gbm-v`.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Nur Teilnehmer dieser Art.", "schema": { "type": "string", "enum": [ "hub", "mandant", "team" ] }, "example": "team" }, { "name": "home", "in": "query", "required": false, "description": "Nur Teams dieses Heimatsystems (Kennung des Hubs oder eines Mandanten).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Die Teilnehmer der Organisation (gefiltert).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantList" }, "example": { "participants": [ { "slug": "gbm-v-mobil-1", "name": "GBM-V Mobiles Team 1", "kind": "team", "home": "gbm-v", "status": "active", "contact_email": null, "public_key_fingerprint": null, "activated_at": "2026-10-01T08:00:00Z", "deactivated_at": null, "last_activity_at": "2026-11-13T08:55:00Z", "created_at": "2026-10-01T07:30:00Z" } ] } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } }, "post": { "operationId": "createParticipant", "tags": [ "Verwaltung" ], "summary": "Mandant oder Team anlegen", "description": "Legt einen Mandanten (`kind` `mandant`, Standard) oder ein Team (`kind` `team` mit `home`) mit Status `invited` an und stellt einen einmaligen Anmeldecode aus. Ein Mandant bekommt die Routen Hub → Mandant und Mandant → Hub, ein Team die Routen Team → Heimatsystem und Heimatsystem → Team. Heimatsystem ist der Hub oder ein nicht deaktivierter Mandant, sonst `422 invalid_home`. Teams zählen nicht zur Höchstzahl der Mandanten. Den Code auf sicherem Weg weitergeben; damit wird über `POST /enroll` angemeldet.", "security": [ { "organisationKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewParticipant" }, "example": { "slug": "def-v", "name": "Muster GmbH", "contact_email": "it@example.org", "kind": "mandant" } } } }, "responses": { "201": { "description": "Der Mandant und sein Anmeldecode. Der Code wird nur dieses eine Mal gezeigt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedParticipant" }, "example": { "participant": { "slug": "def-v", "name": "Muster GmbH", "kind": "mandant", "home": null, "status": "invited", "contact_email": "it@example.org", "public_key_fingerprint": null, "activated_at": null, "deactivated_at": null, "last_activity_at": null, "created_at": "2026-10-01T07:30:00Z" }, "enrollment_code": { "code": "ABCDE-FGHJK-MNPQR", "id": 12, "label": "Laptop Empfang", "expires_at": "2026-11-27T09:00:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `forbidden`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "forbidden" ] } } } } } ] }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "Für diese Aktion fehlt die Berechtigung." } } } } } } }, "409": { "description": "Fehler: `slug_taken`, `limit_reached`, `hub_missing`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "slug_taken", "limit_reached", "hub_missing" ] } } } } } ] }, "examples": { "slug_taken": { "summary": "slug_taken", "value": { "error": { "code": "slug_taken", "message": "Diese Kennung ist in der Organisation bereits vergeben oder reserviert." } } }, "limit_reached": { "summary": "limit_reached", "value": { "error": { "code": "limit_reached", "message": "Die Organisation hat ihre Höchstzahl an Mandanten erreicht." } } }, "hub_missing": { "summary": "hub_missing", "value": { "error": { "code": "hub_missing", "message": "Die Organisation hat noch kein eigenes System (Hub). Bitte an Berlin Bird wenden." } } } } } } }, "422": { "description": "Fehler: `validation_failed`, `invalid_home`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed", "invalid_home" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } }, "invalid_home": { "summary": "invalid_home", "value": { "error": { "code": "invalid_home", "message": "Das Heimatsystem des Teams ist unbekannt, deaktiviert oder selbst ein Team. Heimatsystem ist der Hub oder ein Mandant derselben Organisation." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}": { "get": { "operationId": "getParticipant", "tags": [ "Verwaltung" ], "summary": "Teilnehmer lesen", "description": "Ein Teilnehmer der eigenen Organisation.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers (Hub, Mandant oder Team).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Der Teilnehmer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResponse" }, "example": { "participant": { "slug": "gbm-v", "name": "GBM-V", "kind": "mandant", "home": null, "status": "active", "contact_email": null, "public_key_fingerprint": null, "activated_at": "2026-10-01T08:00:00Z", "deactivated_at": null, "last_activity_at": "2026-11-13T08:55:00Z", "created_at": "2026-10-01T07:30:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } }, "patch": { "operationId": "updateParticipant", "tags": [ "Verwaltung" ], "summary": "Teilnehmer ändern", "description": "Ändert `name` und/oder `contact_email` (`null` löscht die Kontaktadresse). Der `slug` bleibt immer gleich; auch der Hub kann umbenannt werden.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers (Hub, Mandant oder Team).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantChanges" }, "example": { "name": "GBM-V Verwaltung", "contact_email": null } } } }, "responses": { "200": { "description": "Der geänderte Teilnehmer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResponse" }, "example": { "participant": { "slug": "gbm-v", "name": "GBM-V Verwaltung", "kind": "mandant", "home": null, "status": "active", "contact_email": null, "public_key_fingerprint": null, "activated_at": "2026-10-01T08:00:00Z", "deactivated_at": null, "last_activity_at": "2026-11-13T08:55:00Z", "created_at": "2026-10-01T07:30:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "422": { "description": "Fehler: `validation_failed`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } }, "delete": { "operationId": "removeParticipant", "tags": [ "Verwaltung" ], "summary": "Mandant oder Team beenden", "description": "Beendet einen Mandanten oder ein Team endgültig: Schlüssel, Anmeldecodes, Routen und alle noch wartenden Nachrichten von und an ihn werden gelöscht. Die Teams eines Mandanten werden mit ihm beendet. Der Absender jeder gelöschten wartenden Nachricht bekommt eine Systemnachricht `system.participant_removed`. Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "204": { "description": "Der Mandant ist beendet." }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`, `forbidden`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub", "forbidden" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } }, "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "Für diese Aktion fehlt die Berechtigung." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/deactivate": { "post": { "operationId": "deactivateParticipant", "tags": [ "Verwaltung" ], "summary": "Mandant oder Team deaktivieren", "description": "Stoppt den Austausch: Die Schlüssel funktionieren sofort nicht mehr, es kann nichts mehr an ihn gesendet werden (`403 route_not_allowed`). Wartende Nachrichten bleiben liegen. Die Teams eines Mandanten werden mit ihm deaktiviert. Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Der Mandant mit neuem Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResponse" }, "example": { "participant": { "slug": "gbm-v", "name": "GBM-V", "kind": "mandant", "home": null, "status": "deactivated", "contact_email": null, "public_key_fingerprint": null, "activated_at": "2026-10-01T08:00:00Z", "deactivated_at": "2026-11-13T09:00:00Z", "last_activity_at": "2026-11-13T08:55:00Z", "created_at": "2026-10-01T07:30:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`, `forbidden`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub", "forbidden" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } }, "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "Für diese Aktion fehlt die Berechtigung." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/reactivate": { "post": { "operationId": "reactivateParticipant", "tags": [ "Verwaltung" ], "summary": "Mandant oder Team wieder aktivieren", "description": "Nimmt den Austausch wieder auf. Wer nie angemeldet war, wird wieder `invited`. Bei einem nicht deaktivierten Teilnehmer ändert sich nichts. Die Teams eines Mandanten bleiben deaktiviert und werden einzeln wieder aktiviert; ein Team erst, wenn sein Heimatsystem aktiv ist (sonst `422 invalid_home`). Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Der Mandant mit neuem Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResponse" }, "example": { "participant": { "slug": "gbm-v", "name": "GBM-V", "kind": "mandant", "home": null, "status": "active", "contact_email": null, "public_key_fingerprint": null, "activated_at": "2026-10-01T08:00:00Z", "deactivated_at": null, "last_activity_at": "2026-11-13T08:55:00Z", "created_at": "2026-10-01T07:30:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`, `forbidden`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub", "forbidden" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } }, "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "Für diese Aktion fehlt die Berechtigung." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "422": { "description": "Fehler: `invalid_home`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_home" ] } } } } } ] }, "examples": { "invalid_home": { "summary": "invalid_home", "value": { "error": { "code": "invalid_home", "message": "Das Heimatsystem des Teams ist unbekannt, deaktiviert oder selbst ein Team. Heimatsystem ist der Hub oder ein Mandant derselben Organisation." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/enrollment-code": { "post": { "operationId": "issueEnrollmentCode", "tags": [ "Verwaltung" ], "summary": "Neuen Anmeldecode ausstellen", "description": "Stellt einen neuen einmaligen Anmeldecode aus, z. B. für ein weiteres Gerät (ein Code je Gerät) oder nach verlorenem oder gesperrtem Schlüssel. Offene frühere Codes bleiben gültig: Mehrere Geräte können parallel angemeldet werden (ein Code je Gerät, höchstens 20 offene Codes je Teilnehmer, sonst `422 enrollment_code_limit`). Der optionale `label` (Gerätename) wird zur Bezeichnung des Schlüssels, der bei `POST /enroll` entsteht, sofern die Anmeldung keinen eigenen `label` sendet. Mit `?replace=true` gilt das frühere Verhalten: Alle noch offenen Codes werden vorher ungültig (Geräte nacheinander anmelden). Die bisherigen Antwortfelder bleiben; `id` und `label` sind neu. Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" }, { "name": "replace", "in": "query", "required": false, "description": "Mit `true` werden alle noch offenen Codes des Teilnehmers vorher ungültig (früheres Verhalten); sonst bleiben sie gültig.", "schema": { "type": "boolean", "default": false }, "example": false } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewEnrollmentCode" }, "example": { "label": "Laptop Empfang" } } } }, "responses": { "201": { "description": "Der neue Code. Er wird nur dieses eine Mal gezeigt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentCodeResponse" }, "example": { "enrollment_code": { "code": "ABCDE-FGHJK-MNPQR", "id": 12, "label": "Laptop Empfang", "expires_at": "2026-11-27T09:00:00Z" } } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "422": { "description": "Fehler: `validation_failed`, `enrollment_code_limit`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed", "enrollment_code_limit" ] } } } } } ] }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "Die Anfrage ist ungültig." } } }, "enrollment_code_limit": { "summary": "enrollment_code_limit", "value": { "error": { "code": "enrollment_code_limit", "message": "Zu viele offene Anmeldecodes: höchstens :max je Teilnehmer. Nicht mehr benötigte Codes zurückziehen oder mit ?replace=true alle offenen ersetzen." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/enrollment-codes": { "get": { "operationId": "listEnrollmentCodes", "tags": [ "Verwaltung" ], "summary": "Offene Anmeldecodes auflisten", "description": "Die Anmeldecodes, die noch offen sind (nicht benutzt, nicht abgelaufen), älteste zuerst. Nur Bezeichnung und Zeiten, nie der Code selbst. Mit der `id` zieht `DELETE /participants/{slug}/enrollment-codes/{id}` einen Code zurück.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers (Hub, Mandant oder Team).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Die offenen Codes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentCodeList" }, "example": { "enrollment_codes": [ { "id": 12, "label": "Laptop Empfang", "created_at": "2026-11-13T09:00:00Z", "expires_at": "2026-11-27T09:00:00Z" } ] } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/enrollment-codes/{id}": { "delete": { "operationId": "cancelEnrollmentCode", "tags": [ "Verwaltung" ], "summary": "Einen Anmeldecode zurückziehen", "description": "Zieht einen noch offenen Anmeldecode zurück (z. B. für ein Gerät, das doch nicht angemeldet wird). Die anderen offenen Codes bleiben gültig.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers (Hub, Mandant oder Team).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" }, { "name": "id", "in": "path", "required": true, "description": "Die `id` des Codes aus `GET /participants/{slug}/enrollment-codes`.", "schema": { "type": "string", "pattern": "^[0-9]+$" }, "example": "12" } ], "responses": { "204": { "description": "Der Code ist zurückgezogen." }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } }, "not_found_code": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen offenen Anmeldecode gibt es bei diesem Teilnehmer nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/keys/revoke": { "post": { "operationId": "revokeParticipantKeys", "tags": [ "Verwaltung" ], "summary": "Alle Schlüssel sperren", "description": "Sperrt sofort alle Teilnehmerschlüssel des Mandanten oder Teams (z. B. bei Verdacht auf Missbrauch). Danach wird mit einem neuen Anmeldecode wieder angemeldet. Einen einzelnen Schlüssel (ein Gerät) sperrt `DELETE /participants/{slug}/keys/{prefix}`. Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Zahl der gesperrten Schlüssel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedKeys" }, "example": { "revoked": 1 } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`, `forbidden`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub", "forbidden" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } }, "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "Für diese Aktion fehlt die Berechtigung." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/keys": { "get": { "operationId": "listParticipantKeys", "tags": [ "Verwaltung" ], "summary": "Schlüssel auflisten", "description": "Die Teilnehmerschlüssel, die gerade gelten (nicht gesperrt, nicht abgelaufen), älteste zuerst; je Gerät einer. Nur Präfix und Bezeichnung, nie der Schlüssel selbst. Auch für den Hub. Die Schlüssel eines deaktivierten Teilnehmers stehen weiter in der Liste, funktionieren aber erst nach der Reaktivierung.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Teilnehmers (Hub, Mandant oder Team).", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" } ], "responses": { "200": { "description": "Die geltenden Schlüssel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantKeyList" }, "example": { "keys": [ { "prefix": "dbk_Lp7Qx2Ra", "label": "Laptop Empfang", "created_at": "2026-10-01T08:00:00Z", "last_used_at": "2026-11-13T08:55:00Z", "expires_at": null } ] } } } }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/participants/{slug}/keys/{prefix}": { "delete": { "operationId": "revokeParticipantKey", "tags": [ "Verwaltung" ], "summary": "Einen Schlüssel sperren", "description": "Sperrt sofort den geltenden Teilnehmerschlüssel mit diesem Präfix (z. B. eines verlorenen Geräts). Die anderen Schlüssel des Mandanten oder Teams gelten weiter. Nicht für den Hub.", "security": [ { "organisationKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kennung des Mandanten oder Teams.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "example": "gbm-v" }, { "name": "prefix", "in": "path", "required": true, "description": "Präfix des Schlüssels aus `GET /participants/{slug}/keys`.", "schema": { "type": "string", "maxLength": 32 }, "example": "dbk_Lp7Qx2Ra" } ], "responses": { "204": { "description": "Der Schlüssel ist gesperrt." }, "401": { "description": "Fehler: `unauthenticated`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "unauthenticated" ] } } } } } ] }, "examples": { "unauthenticated": { "summary": "unauthenticated", "value": { "error": { "code": "unauthenticated", "message": "Das API-Token fehlt oder ist ungültig." } } } } } } }, "403": { "description": "Fehler: `not_allowed_for_hub`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_allowed_for_hub" ] } } } } } ] }, "examples": { "not_allowed_for_hub": { "summary": "not_allowed_for_hub", "value": { "error": { "code": "not_allowed_for_hub", "message": "Diese Änderung ist für das eigene System der Organisation (Hub) nicht möglich." } } } } } } }, "404": { "description": "Fehler: `not_found`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen Teilnehmer gibt es in dieser Organisation nicht." } } }, "not_found_key": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Diesen aktiven Schlüssel gibt es bei diesem Teilnehmer nicht." } } } } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiJson", "tags": [ "Dokumentation" ], "summary": "Diese Beschreibung als JSON", "description": "Die OpenAPI-3.1-Beschreibung der API (ohne Plattform-Admin-Operationen).", "security": [], "responses": { "200": { "description": "OpenAPI-Dokument.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } }, "/openapi.yaml": { "get": { "operationId": "getOpenApiYaml", "tags": [ "Dokumentation" ], "summary": "Diese Beschreibung als YAML", "description": "Dasselbe Dokument wie `/openapi.json` im YAML-Format.", "security": [], "responses": { "200": { "description": "OpenAPI-Dokument.", "content": { "application/yaml": { "schema": { "type": "string" } } } }, "429": { "description": "Fehler: `too_many_requests`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "too_many_requests" ] } } } } } ] }, "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "error": { "code": "too_many_requests", "message": "Zu viele Aufrufe in kurzer Zeit. Bitte nach der Zeit im Header Retry-After wiederholen." } } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Fehler: `server_error`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "server_error" ] } } } } } ] }, "examples": { "server_error": { "summary": "server_error", "value": { "error": { "code": "server_error", "message": "Störung im Dienst. Bitte später mit derselben id wiederholen." } } } } } } } } } } }, "components": { "securitySchemes": { "participantKey": { "type": "http", "scheme": "bearer", "description": "Teilnehmerschlüssel (`dbk_…`) eines Hubs oder Mandanten. Ein Mandant bekommt ihn mit `POST /enroll`." }, "organisationKey": { "type": "http", "scheme": "bearer", "description": "Organisationsschlüssel (`dbk_…`), nur für die Verwaltung der Mandanten. Ausgestellt von Berlin Bird oder in der Verwaltungsoberfläche. Ein auf einen Mandanten beschränkter Schlüssel sieht und verwaltet nur diesen Mandanten und die Teams, deren Heimatsystem er ist: Anderes gibt es für ihn nicht (`404`), Mandanten anlegen sowie den eigenen Mandanten deaktivieren, reaktivieren oder beenden ist verboten (`403 forbidden`), Teams nur mit diesem Mandanten als `home`." } }, "schemas": { "Error": { "type": "object", "description": "Form jedes Fehlers. Programme werten `code` aus; `message` ist ein deutscher Text für Menschen.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stabiler Fehlercode.", "examples": [ "validation_failed" ] }, "message": { "type": "string", "description": "Deutsche Beschreibung, kann sich ändern." } } } } }, "Slug": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Kennung eines Teilnehmers oder einer Organisation, z. B. `gtm-v`." }, "Timestamp": { "type": "string", "format": "date-time", "description": "Zeitpunkt in UTC, z. B. `2026-11-13T09:00:00Z`." }, "Ping": { "type": "object", "required": [ "participant", "organisation", "time" ], "properties": { "participant": { "$ref": "#/components/schemas/Slug" }, "organisation": { "$ref": "#/components/schemas/Slug" }, "time": { "$ref": "#/components/schemas/Timestamp" } } }, "NewMessage": { "type": "object", "description": "Eine neue Nachricht.", "required": [ "id", "to", "type", "payload" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Vom Absender erzeugte UUID; bei Wiederholung dieselbe." }, "to": { "type": "string", "maxLength": 64, "description": "Kennung des Empfängers." }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Frei wählbarer Nachrichtentyp, z. B. `spende.meldung`." }, "payload": { "type": "string", "contentEncoding": "base64", "description": "Inhalt als Base64 (vorzugsweise Ende-zu-Ende verschlüsselt). Größe nach dem Dekodieren höchstens das Limit der Organisation (Standard 5 MiB)." } } }, "MessageEnvelope": { "type": "object", "description": "Umschlag einer Nachricht: alles außer dem Inhalt.", "required": [ "id", "from", "to", "type", "created", "size" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "$ref": "#/components/schemas/Slug", "description": "Absender; `system` bei Nachrichten des Dienstes." }, "to": { "$ref": "#/components/schemas/Slug", "description": "Empfänger." }, "type": { "type": "string" }, "created": { "$ref": "#/components/schemas/Timestamp", "description": "Zeitpunkt des Einlegens." }, "size": { "type": "integer", "minimum": 0, "description": "Größe des Inhalts in Bytes (dekodiert)." } } }, "Message": { "type": "object", "description": "Eine Nachricht: Umschlag und Inhalt.", "required": [ "id", "from", "to", "type", "created", "size", "payload" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "$ref": "#/components/schemas/Slug", "description": "Absender; `system` bei Nachrichten des Dienstes." }, "to": { "$ref": "#/components/schemas/Slug", "description": "Empfänger." }, "type": { "type": "string" }, "created": { "$ref": "#/components/schemas/Timestamp", "description": "Zeitpunkt des Einlegens." }, "size": { "type": "integer", "minimum": 0, "description": "Größe des Inhalts in Bytes (dekodiert)." }, "payload": { "type": "string", "contentEncoding": "base64", "description": "Inhalt als Base64." } } }, "MessageList": { "type": "object", "description": "Wartende Nachrichten, älteste zuerst (Seite ohne Cursor, siehe `more`).", "required": [ "messages", "more" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEnvelope" } }, "more": { "type": "boolean", "description": "`true`, wenn weitere Nachrichten warten. Blättern: die gelieferten abholen und quittieren, dann erneut auflisten." } } }, "PublicKey": { "type": "object", "required": [ "participant", "public_key", "fingerprint", "updated_at" ], "properties": { "participant": { "$ref": "#/components/schemas/Slug" }, "public_key": { "type": [ "string", "null" ], "description": "Der veröffentlichte öffentliche Schlüssel (undurchsichtiger Text) oder `null`." }, "fingerprint": { "type": [ "string", "null" ], "description": "`SHA256:` und SHA-256 des Schlüssels als Hex, oder `null`." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PublicKeyUpdate": { "type": "object", "required": [ "public_key" ], "properties": { "public_key": { "type": "string", "minLength": 1, "maxLength": 16384 } } }, "KeyRotation": { "type": "object", "properties": { "immediate": { "type": "boolean", "default": false, "description": "`true` = den bisherigen Schlüssel und seine ganze Tauschkette (Nachfolger und Vorgänger in der Übergangszeit) sofort ungültig machen, z. B. bei Verdacht auf ein Leck. `false` (Standard) = Übergangszeit von 24 Stunden." } } }, "RotatedKey": { "type": "object", "required": [ "participant_key", "previous_key_expires_at" ], "properties": { "participant_key": { "type": "string", "description": "Der neue Teilnehmerschlüssel." }, "previous_key_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Ablauf des bisherigen Schlüssels; bei `immediate: true` der Zeitpunkt des Aufrufs (sofort ungültig)." } } }, "EnrollmentRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "maxLength": 64, "description": "Der Anmeldecode, z. B. `ABCDE-FGHJK-MNPQR`." }, "label": { "type": [ "string", "null" ], "maxLength": 100, "description": "Optional: Bezeichnung des neuen Schlüssels, z. B. der Gerätename. Erscheint in `GET /participants/{slug}/keys`." }, "public_key": { "type": [ "string", "null" ], "maxLength": 16384, "description": "Optional: eigener öffentlicher Schlüssel." } } }, "EnrollmentResult": { "type": "object", "required": [ "participant", "organisation", "hub", "kind", "home", "participant_key", "public_key" ], "properties": { "participant": { "$ref": "#/components/schemas/Slug", "description": "Der eigene Teilnehmer." }, "organisation": { "$ref": "#/components/schemas/Slug" }, "hub": { "type": [ "string", "null" ], "description": "Kennung des Systems, an das Nachrichten gehen: der Hub, bei einem Team sein Heimatsystem." }, "kind": { "type": "string", "enum": [ "mandant", "team" ], "description": "Art des eigenen Teilnehmers." }, "home": { "type": [ "string", "null" ], "description": "Bei einem Team die Kennung seines Heimatsystems (gleich `hub`), sonst `null`." }, "participant_key": { "type": "string", "description": "Der eigene Teilnehmerschlüssel." }, "public_key": { "oneOf": [ { "$ref": "#/components/schemas/PublicKey" }, { "type": "null" } ] } } }, "Participant": { "type": "object", "description": "Hub, Mandant oder Team einer Organisation.", "required": [ "slug", "name", "kind", "home", "status", "contact_email", "public_key_fingerprint", "activated_at", "deactivated_at", "last_activity_at", "created_at" ], "properties": { "slug": { "$ref": "#/components/schemas/Slug" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "hub", "mandant", "team" ] }, "home": { "type": [ "string", "null" ], "description": "Bei einem Team die Kennung seines Heimatsystems (Hub oder Mandant), sonst `null`." }, "status": { "type": "string", "enum": [ "invited", "active", "deactivated" ], "description": "`invited` bis zur Anmeldung, dann `active`; `deactivated` nach Deaktivierung." }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "public_key_fingerprint": { "type": [ "string", "null" ], "description": "SHA-256-Fingerabdruck des veröffentlichten öffentlichen Schlüssels (`SHA256:…`), `null` ohne Schlüssel." }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deactivated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Letzte Nutzung eines Schlüssels des Teilnehmers." }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ParticipantResponse": { "type": "object", "required": [ "participant" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" } } }, "ParticipantList": { "type": "object", "required": [ "participants" ], "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } }, "EnrollmentCode": { "type": "object", "required": [ "code", "id", "label", "expires_at" ], "properties": { "code": { "type": "string", "description": "Einmaliger Anmeldecode." }, "id": { "type": "integer", "description": "Kennung des Codes für `DELETE /participants/{slug}/enrollment-codes/{id}`." }, "label": { "type": [ "string", "null" ], "maxLength": 100, "description": "Gerätename, falls beim Ausstellen angegeben." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "EnrollmentCodeList": { "type": "object", "required": [ "enrollment_codes" ], "properties": { "enrollment_codes": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "created_at", "expires_at" ], "properties": { "id": { "type": "integer" }, "label": { "type": [ "string", "null" ], "maxLength": 100 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } } } } } }, "NewEnrollmentCode": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "maxLength": 100, "description": "Gerätename; wird zur Bezeichnung des Schlüssels bei `POST /enroll`." } } }, "EnrollmentCodeResponse": { "type": "object", "required": [ "enrollment_code" ], "properties": { "enrollment_code": { "$ref": "#/components/schemas/EnrollmentCode" } } }, "CreatedParticipant": { "type": "object", "required": [ "participant", "enrollment_code" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" }, "enrollment_code": { "$ref": "#/components/schemas/EnrollmentCode" } } }, "NewParticipant": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "$ref": "#/components/schemas/Slug", "description": "Kennung des Mandanten oder Teams, nicht änderbar." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "kind": { "type": "string", "enum": [ "mandant", "team" ], "default": "mandant" }, "home": { "$ref": "#/components/schemas/Slug", "description": "Kennung des Heimatsystems (Hub oder Mandant): bei `kind` `team` Pflicht, sonst nicht erlaubt." } } }, "ParticipantChanges": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } } }, "ParticipantKeyList": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "required": [ "prefix", "label", "created_at", "last_used_at", "expires_at" ], "properties": { "prefix": { "type": "string", "description": "Präfix des Schlüssels (kein Geheimnis), für `DELETE /participants/{slug}/keys/{prefix}`." }, "label": { "type": [ "string", "null" ], "description": "Bezeichnung, z. B. der Gerätename aus `POST /enroll`." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` = läuft nicht ab; gesetzt z. B. nach einem Schlüsseltausch." } } } } } }, "RevokedKeys": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "integer", "minimum": 0, "description": "Zahl der gesperrten Schlüssel." } } } }, "headers": { "RetryAfter": { "description": "Sekunden, nach denen der Aufruf wiederholt werden darf.", "schema": { "type": "integer", "minimum": 0 } } } } }