API-Authentifizierung: So funktioniert der Auth-Flow
Alle Schnittstellen der Werkzettel-API sind mandantengebunden und geschützt. Wer Automatisierungen anbinden will — zum Beispiel Abrechnungssysteme oder BI-Dashboards — muss den Auth-Flow korrekt implementieren.
Der Ablauf in Kurzform:
- Login: Sendet die Zugangsdaten per POST an den Login-Endpunkt der API. Im Request entscheidet der
Host-Header, zu welchem Mandanten die Anfrage gehört — der Mandant wird niemals aus dem Request-Body oder einer Client-Parameterliste gelesen. Das ist Absicht: So kann ein manipulierter Client nicht in den Datenraum eines anderen Betriebs springen. - Session-Token: Bei erfolgreichem Login liefert die API ein Token mit Ablaufzeit. Das Token gehört zur Session — es ist an den Mandanten gebunden und berechtigt nur innerhalb dieses Mandanten.
- Aufrufe geschützter Endpunkte: Sendet das Token bei jedem Request im
Authorization-Header nach dem Bearer-Schema:Authorization: Bearer <token>. - Ablauf: Nach Ablauf der Session antwortet die API mit
401 Unauthorized. Implementiert dann einen sauberen Re-Login, statt tokenlose Requests wiederholt zu verschicken.
Regeln für Integrationen:
- Kein Token in URLs oder Query-Parametern — sie landen in Logs.
- Tokens niemals hardcoden; bei Automatisierungen gehört der Zugang in den Secret-Store eurer Plattform.
- Ein Token ist nur für den Mandanten gültig, dem es ausgestellt wurde. Querstehende Aufrufe anderer Mandanten schlagen mit
403fehl. - Wer seinen Token nicht mehr kontrolliert, muss den Zugang über die Betriebskonsole sperren und ein neues Konto bzw. neue Zugangsdaten verteilen.
Wenn eure Requests scheitern, schaut in die Fehlercodes: 401 heißt fehlende oder abgelaufene Authentifizierung, 403 heißt fehlende Berechtigung für die angefragte Ressource. Beides zusammen deckt die häufigsten Integrationsprobleme ab.