API-Schlüssel (Maschinenzugriff): Handbuch

Florian bietet eine REST-API für Maschinenzugriff — etwa für eigene Skripte, ein Auswertungs-Dashboard oder die Anbindung von Drittsystemen. Der Zugriff läuft über API-Schlüssel, die in der Verwaltung erstellt werden und exakt die Rechte tragen, die Sie ihnen geben.

Entwicklungsstand 24.10.2026: Die nachfolgende Absicherung der Verwaltungsaktionen ist lokal implementiert; der Produktionsrollout steht noch aus.

Grundprinzipien

Minimalrechte: Jeder Schlüssel erhält beim Erstellen eine explizite Auswahl aus Modul-Berechtigungen (z. B. nur Geräte: Ansehen). Mehr kann er nie — auch nicht „implizit": Verwalten schließt Ansehen nicht automatisch ein; was der Schlüssel können soll, wird einzeln angehakt.
Delegationsgrenze: In der Verwaltungsoberfläche erfordern Erstellen und Widerrufen ein aktuell aktives Konto der eigenen Wehr und uneingeschränktes API-Schlüssel: Verwalten. Jede ausgewählte Modul-/Aktionsberechtigung muss auch dem erstellenden Benutzer uneingeschränkt zustehen. Eigene Datensätze, Jugendfeuerwehr-/Wehr-Scope oder gesperrte Felder lassen sich nicht in einem Maschinenschlüssel abbilden und dürfen deshalb nicht delegiert werden. Bereits geöffnete Dialoge prüfen diese Rechte vor der Änderung erneut.
REST-Widerruf: Bei angemeldeten Benutzern prüft die API vor jedem Widerruf uneingeschränktes API-Schlüssel: Verwalten. Auf eigene Datensätze, Jugendfeuerwehr oder Wehr begrenzte Verwaltungsrechte reichen dafür nicht aus. Maschinen dürfen mit der ausdrücklich vergebenen Schlüsselberechtigung API-Schlüssel: Verwalten Schlüssel der eigenen Wehr widerrufen; Ansehen allein genügt nicht.
Einmal sichtbar: Der Klartext-Schlüssel (fw_…) wird genau einmal angezeigt — beim Erstellen. Danach speichert Florian nur einen Argon2id-Hash; verlorene Schlüssel werden ersetzt, nicht wiederhergestellt.
Ablauf & Widerruf: Optional mit Ablaufdatum; jederzeit widerrufbar. Erstellen und Widerrufen landen im Audit-Log. In der Verwaltungsoberfläche werden Änderung und Audit-Eintrag zusammen gespeichert: Scheitert dieser Eintrag, wird die Änderung zurückgerollt. Dort erscheint ein erfolgreich erzeugter Klartextschlüssel erst nach dem Speichern. Diese Rückfallgarantie gilt für die beiden Oberflächenaktionen; der REST-Widerruf besitzt derzeit keine entsprechende gemeinsame Transaktion. Der spätere Entzug von Benutzerrechten widerruft bereits ausgegebene Schlüssel nicht automatisch; diese müssen separat widerrufen werden.

Verwendung

Der Schlüssel wird als HTTP-Header mitgesendet:

X-Api-Key: fw_…

Beispiel — ein Gerät per Barcode auflösen:

curl -H "X-Api-Key: fw_…" \
  "https://ihr-florian-server/api/geraete/by-barcode/FLC-0042"

Antworten sind JSON. Fehlende Berechtigungen ergeben 403 mit einer klaren Fehlermeldung, ein ungültiger oder abgelaufener Schlüssel 401.

Beim Erstellen über POST /api/admin/api-keys/ muss Scope mindestens eine Berechtigung enthalten. null, eine leere Liste oder null-Einträge in der Liste werden mit 400 und einer JSON-Validierungsantwort zum betroffenen Feld zurückgewiesen. Dabei wird kein Schlüssel angelegt; eine gemischte Liste aus gültigen Berechtigungen und null wird vollständig zurückgewiesen.

Sicherheitshinweise

Schlüssel wie Passwörter behandeln: nie in Quelltext oder Chats, nur in Umgebungsvariablen/Secret-Stores.
Pro System ein eigener Schlüssel — so lässt sich ein einzelnes System gezielt widerrufen.
Ablaufdatum setzen, wo der Einsatz zeitlich begrenzt ist.
Die Web-Anmeldung (Cookie) und der Maschinenzugriff (Header) sind strikt getrennt: Ein Request mit X-Api-Key-Header wird ausschließlich über den Schlüssel geprüft — ein ungültiger Schlüssel fällt niemals still auf eine bestehende Browser-Sitzung zurück.