Darstellung
Authentifizierung und Scopes
API-Schlüssel
Jeder Aufruf trägt einen Schlüssel im Authorization-Header:
http
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 mit401 unauthorized. last_used_atzeigt 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, /kontakte | immer verfügbar |
anfragen | /anfragen | write für das Anlegen aus Website-Formularen |
rapport | /rapports | |
angebote | /offers | |
rechnungen | /invoices | |
zeiterfassung | /time-entries | |
termine | /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.
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.
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
anfragen: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.