API-Schlüssel
Ein API-Schlüssel lässt ein anderes Programm mit WorkOffice sprechen – ohne Benutzername und Passwort einer Person. Er gilt nur für diesen Betrieb und nur mit seinen Rechten.
Zu finden unter Einstellungen → WorkTime Pro & API (im Menü: Verwaltung → WorkTime Pro). Schlüssel verwalten Inhaber und Büro (Recht apikey:manage):
Schnittstellen und API-Schlüssel verwaltet der Inhaber oder das Büro.
API-Schlüssel und die Lexware-kompatible Schnittstelle stecken in jedem Paket.
Zwei Arten
| Art | Wofür | Wo |
|---|---|---|
| Verbindung zu WorkTime Pro | die direkte Anbindung von WorkTime Pro (/api/worktime/v1) | oben, Mit WorkTime verbinden – siehe WorkTime Pro anbinden |
| API-Schlüssel | die Lexware-kompatible Schnittstelle (/api/lexware/v1) für ältere WorkTime-Fassungen, Shops, Zahlungsdienste, Scan-Apps und eigene Werkzeuge | weiter unten, Karte API-Schlüssel |
Ein Schlüssel der einen Art gilt nicht für die andere Schnittstelle. Beide haben die Form wo_ plus acht Zeichen, Punkt, Geheimnis.
Schlüssel erzeugen
In der Karte Schlüssel erzeugen einen Namen vergeben, an dem man ihn später erkennt, und eine Vorlage für die Rechte wählen:
| 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 |
Festschreiben gehört zu keiner Vorlage – das geschieht in WorkOffice. Erzeugen zeigt den Schlüssel:
Jetzt kopieren und in WorkTime Pro eintragen – er wird nur dieses eine Mal angezeigt.
WorkOffice speichert nur einen Prüfwert (Hash) des Schlüssels; der Schlüssel selbst steht nirgends in der Datenbank. Wer ihn verliert, erzeugt einen neuen und widerruft den alten.
Ein Schlüssel darf nicht mehr als sein Aussteller. Wer über die Schnittstelle eigene Rechte wählt, bekommt nur bekannte Rechte aus dem Katalog – und nur solche, die er selbst hat. Sonst könnte sich jemand über einen Schlüssel mehr erlauben, als seine Rolle hergibt. Siehe Rollen und Rechte.
Benutzen
Das andere Programm schickt den Schlüssel bei jeder Anfrage mit – als Authorization: Bearer wo_… wie bei Lexware Office oder im Kopffeld X-API-Key. Erlaubt sind 300 Anfragen je Minute und Schlüssel. Was mit Lexware Office spricht, spricht auch mit WorkOffice: Im anderen Programm wird nur die Adresse umgestellt und der WorkOffice-Schlüssel eingetragen.
Die Liste zeigt je Schlüssel Namen, Rechte, wann er erzeugt und wann er zuletzt benutzt wurde. Im Prüfprotokoll stehen Einträge, die über einen Schlüssel entstanden sind, als „API-Schlüssel“.
Widerrufen
Widerrufen nimmt einem Programm sofort den Zugang:
Schlüssel „Shop“ (wo_AbCd1234…) widerrufen? Programme, die ihn benutzen, verlieren sofort den Zugang.
Programme, die über diesen Schlüssel Ereignisse abonniert haben, erfahren es ein letztes Mal. Widerrufene Schlüssel stehen darunter weiter in der Liste.
Webhooks
Auf derselben Seite stehen der Signaturschlüssel für Webhooks, die abonnierten Ereignisse und die letzten Zustellungen mit Erneut senden. Was die Schnittstelle kann – Endpunkte, Ereignisse, Signatur, Wiederholungen – beschreibt der Bereich Schnittstellen.
Ohne laufendes Abo steht auch die Schnittstelle auf „nur lesen“: Programme können lesen, aber nichts anlegen.