Authentifizierung
Zwei Wege führen hinein: für Menschen im Browser die Sitzung der Oberfläche, für Programme der API-Schlüssel. Programme sollten immer einen Schlüssel nehmen – er hat eigene, engere Rechte, lässt sich einzeln widerrufen und kennt keine Zwei-Faktor-Abfrage.
Der API-Schlüssel
Ein Schlüssel sieht so aus:
wo_Ab3dE6gH.<43 weitere Zeichen>Vorn der sichtbare Teil (wo_ und acht Zeichen), an dem man ihn in der Liste wiedererkennt, hinter dem Punkt das Geheimnis. WorkOffice speichert nur eine Prüfsumme (SHA-256) des ganzen Schlüssels; im Klartext erscheint er genau einmal, direkt nach dem Erzeugen. Wer ihn verliert, erzeugt einen neuen.
Mitgeschickt wird er auf eine von zwei Arten:
curl https://buero.ihrbetrieb.de/api/v1/customers \
-H "X-API-Key: wo_test_ab1.NurEinBeispielKeinEchterSchluessel000000000"
curl https://buero.ihrbetrieb.de/api/lexware/v1/profile \
-H "Authorization: Bearer wo_test_ab1.NurEinBeispielKeinEchterSchluessel000000000"Die zweite Form gibt es, weil Lexware Office seinen Schlüssel als Bearer-Token erwartet – so spricht ein Lexware-Programm WorkOffice an, ohne etwas zu ändern. Als Schlüssel erkannt wird ein Bearer-Token nur, wenn es mit wo_ beginnt.
Zwei Arten von Schlüsseln
| Art | Entsteht unter | Gilt für |
|---|---|---|
| allgemeiner Schlüssel | API-Schlüssel → Schlüssel erzeugen | /api/v1 und /api/lexware/v1 |
| Schlüssel einer WorkTime-Verbindung | Mit WorkTime verbinden | nur /api/worktime/v1 |
Beides steht in der Oberfläche unter Verwaltung → WorkTime Pro (in den Einstellungen der Reiter „WorkTime Pro & API“). Ohne das Paket „Komplett“ trägt der Menüpunkt ein Schloss; die Seite bleibt trotzdem erreichbar, denn die allgemeinen Schlüssel gibt es in jedem Paket. Ein Schlüssel der falschen Art wird abgewiesen, und zwar mit einer Meldung, die sagt, wohin er gehört:
Dieser Schlüssel gilt nur für die WorkTime-Anbindung (/api/worktime/v1).
Die Trennung hat einen Grund: Ein Schlüssel, den WorkTime Pro verwahrt, soll nur können, was der Vertrag mit WorkTime vorsieht – nicht auch Bankumsätze lesen.
Rechte
Die Rechte eines Schlüssels sind seine eigenen, nicht die der Person, die ihn erzeugt hat. Die Regel dabei: Ein Schlüssel darf weniger als der Mensch dahinter, nie mehr. Wer ein Recht selbst nicht hat, kann es auch keinem Schlüssel geben.
Die Oberfläche bietet drei Vorlagen:
| Vorlage | Rechte |
|---|---|
| WorkTime Pro – Kunden, Artikel, Entwürfe (empfohlen) | customer:read, customer:write, article:read, document:read, document:write |
| Belege einreichen – Shops, Zahlungsdienste, Scan-Apps | expense:read, expense:write |
| Nur lesen – Kunden, Artikel, Belege | customer:read, article:read, document:read |
Eine andere Auswahl geht über die Schnittstelle selbst: POST /api/v1/api-keys mit name und einer Liste scopes (höchstens 30 Einträge). Unbekannte oder fremde Rechte weist sie ab:
Diese Rechte haben Sie selbst nicht: …
Festschreiben (document:finalize) steckt in keiner Vorlage mit Absicht: Rechnungsnummer und GoBD-Sperre vergibt der Mensch in WorkOffice, nicht ein Programm.
Fehlt einem Schlüssel ein Recht, antwortet die API mit 403:
Dafür fehlt die Berechtigung: document:finalize
Wer Schlüssel verwaltet
Schlüssel erzeugen, sehen und widerrufen darf, wer das Recht apikey:manage hat – ab Werk der Inhaber und das Büro (siehe Rollen und Rechte). Die Liste zeigt Name, sichtbaren Teil, Rechte und wann der Schlüssel zuletzt benutzt wurde.
Widerrufen wirkt sofort. Programme, die über diesen Schlüssel Webhooks abonniert haben, bekommen ein letztes Ereignis token.revoked, danach nichts mehr.
Wenn der Schlüssel nicht durchkommt
Alle mit 401:
| Meldung | Ursache |
|---|---|
| „API-Schlüssel hat ein unbekanntes Format.“ | kein wo_…, oder das Geheimnis fehlt |
| „API-Schlüssel ungültig.“ | vertippt oder unvollständig kopiert |
| „API-Schlüssel wurde widerrufen.“ | in der Oberfläche widerrufen |
| „Der Betrieb ist gesperrt.“ | der Anbieter hat den Betrieb vollständig gesperrt – dann gehen weder Anmeldung noch Schlüssel |
Steht der Betrieb auf „nur lesen“ (kein Abo, keine gültige Lizenz), gilt das auch für Schlüssel: Lesen geht, Schreiben bekommt 402.
Die Sitzung der Oberfläche
Die Oberfläche meldet sich mit POST /api/v1/auth/login an (email, password, bei mehreren Betrieben mit derselben Adresse zusätzlich tenantSlug). Die Antwort enthält accessToken und expiresIn; das Zugangs-Token gilt ab Werk 900 Sekunden und geht als Authorization: Bearer … mit. Das Erneuerungs-Token steht nicht in der Antwort, sondern kommt als Cookie wo_refresh – httpOnly, SameSite=Strict, im Betrieb Secure, 14 Tage gültig. Ein Skript im Browser kann es so nicht lesen.
Daraus folgt zweierlei: Ohne HTTPS hält die Anmeldung im Betrieb nicht, weil der Browser ein Secure-Cookie über Klartext nicht ablegt. Und für Programme ist dieser Weg unbequem – dafür gibt es den Schlüssel.