Authentifizierung und Scopes

Gilt ab Work7 0.10.0 · Stand 27.10.2026

API-Schlüssel

Jeder Aufruf trägt einen Schlüssel im Authorization-Header:

Authorization: Bearer w7_live_<prefix>_<secret>

• Schlüssel gehören zu genau einem Betrieb (Mandant). Ein Schlüssel sieht nie Daten eines anderen Betriebs.
• Work7 speichert nur Prefix und Hash. Der Klartext erscheint einmalig beim Anlegen.
• Die zweite Stelle nennt die Umgebung: w7_live_… stammt aus der Produktivumgebung, w7_test_… aus einer Testumgebung. So fällt ein versehentlich vertauschter Schlüssel sofort auf.
• Schlüssel lassen sich jederzeit widerrufen (Einstellungen › Integrationen › API & Webhooks oder DELETE /api/company/api-keys/{id} mit einer Admin-Session). Widerrufene Schlüssel antworten mit 401 unauthorized.
• last_used_at zeigt in der Verwaltung, wann ein Schlüssel zuletzt benutzt wurde. Ungenutzte Schlüssel gehören widerrufen.

Scopes

Scopes sind das Berechtigungsmodell der API. Sie kombinieren einen Bereich (Modul) mit einer Zugriffsart:

Scope	Erlaubt
<bereich>:read	Lesen aller Endpunkte des Bereichs
<bereich>:write	Lesen und Schreiben im Bereich

write schließt read ein. Der Bereich core deckt Projekte und Kontakte ab, die es in jedem Work7-Paket gibt.

Bereich	Endpunkte	Bemerkung
core	/me, /projects, /contacts	immer verfügbar; write legt Kontakte an, ändert, archiviert und löscht sie und verknüpft Ansprechpartner, legt Projekte an, ändert sie, wechselt ihren Status und archiviert sie (seit API 1.21; Projekte werden nicht gelöscht)
inquiries	/inquiries	write für das Anlegen aus Website-Formularen
site-reports	/site-reports
offers	/offers
invoices	/invoices
time-tracking	/time-entries
appointments	/appointments
int.inbound	/inbound	Datenablage: Datei-Uploads von Drittsystemen

Ein Schlüssel kann nur Scopes für Bereiche erhalten, die der Betrieb gebucht hat. Die Auswahl in der Verwaltung zeigt automatisch nur diese.

Alte Pfade (/anfragen, /kontakte, /rapports) bleiben als Aliase dauerhaft erreichbar; sie erwarten dieselben Scopes wie oben, unter dem neuen Namen.

Alte Scope-Namen

Seit API 1.2 heißen die Bereiche englisch (anfragen → inquiries, rapport → site-reports, angebote → offers, rechnungen → invoices, zeiterfassung → time-tracking, termine → appointments). Die alten Namen bleiben dauerhaft gültig: POST /api/company/api-keys nimmt sie beim Anlegen eines Schlüssels entgegen und speichert sie als neue Namen (["anfragen:read"] wird zu ["inquiries:read"]). Schlüssel, die schon vor der Umstellung mit alten Scope-Namen angelegt wurden, funktionieren unverändert weiter — ihre Scopes wurden dabei auf die neuen Namen umgeschrieben. 403 insufficient_scope und 403 module_disabled nennen in details immer den neuen Namen.

Was passiert bei fehlender Berechtigung

Situation	Antwort
Kein oder ungültiger Schlüssel	401 unauthorized
Schlüssel hat den nötigen Scope nicht	403 insufficient_scope, details.required nennt den fehlenden Scope
Bereich ist für den Betrieb nicht (mehr) freigeschaltet	403 module_disabled, details.module nennt den Bereich
Public API selbst nicht freigeschaltet	403 module_disabled mit details.module = "int.api"

Wird ein Modul nachträglich abgeschaltet, bleibt der Schlüssel bestehen, seine Scopes für diesen Bereich sind aber wirkungslos, bis das Modul wieder aktiv ist. Bereits erfasste Daten bleiben erhalten.

Rollen-Äquivalent

Jeder Schlüssel arbeitet mit einer Rollenstufe (Standard: Manager). Sie bestimmt, welche Datensätze innerhalb eines Bereichs sichtbar sind, so wie für einen angemeldeten Nutzer derselben Rolle.

Schreibende Aktionen werden dem Nutzer zugeordnet, der den Schlüssel angelegt hat. Eine Anfrage aus POST /inquiries trägt ihn als Ersteller (seit API 1.21, vorher blieb der Ersteller leer). Ist für den Schlüssel kein Ersteller bekannt, bleibt die Zuordnung leer. Anfragen, die die KI-Vorsortierung aus E-Mails anlegt, haben nie einen Ersteller.

Kontakte, die über die API angelegt werden, tragen die Herkunft „API“; der Änderungsverlauf eines Kontakts nennt den Ersteller des Schlüssels wie bei einer Änderung in der App. Bank- und Steuerdaten (iban, bic, vat_number, tax_number) darf ein Schlüssel nur schreiben, wenn seine Rollenstufe sie sehen darf; sonst antwortet die API mit 403, statt die Felder still zu verwerfen.

Projekte, die über die API angelegt werden, tragen ebenfalls die Herkunft „API“; ein Statuswechsel über PATCH /projects/{id} steht im Statusverlauf des Projekts wie ein Wechsel von Hand, mit dem Ersteller des Schlüssels. Projekte anlegen und ändern dürfen nur Schlüssel mit der Rollenstufe Administrator oder Manager; mit der Stufe Mitarbeiter antwortet die API mit 403, bevor sie Projekt oder Kontakt sucht.

Löschen über die API (DELETE /contacts/{id}) entspricht dem Löschen in der App: Der Kontakt wird als gelöscht markiert und ist danach weder lesbar noch änderbar (404). Hat er versendete oder fertiggestellte Belege, lehnt die API mit 409 und details.code has_documents ab; dann den Kontakt archivieren.

Empfehlungen

• Ein Schlüssel je Integration, benannt nach dem System („Buchhaltung“, „Website-Formular“).
• Nur die Scopes vergeben, die die Integration wirklich braucht. Ein Website-Formular braucht nur inquiries:write.
• Schlüssel nie im Browser oder in mobilen Apps einbetten. Aufrufe laufen über den eigenen Server.
• Bei Verdacht auf Verlust sofort widerrufen und neu anlegen.