Authentifizierung, Scopes und Zugang

Beta Die REST-API ist in der Beta. Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern.

Jeder Request an die TimeMonkey REST-API braucht einen API-Key. Der Key bestimmt, zu welchem Standort die Daten gehören und welche Endpunkte abgerufen werden dürfen. Wie du einen Key anlegst, steht im Schnellstart.

API-Key übergeben

Übergib den Key bei jedem Request im HTTP-Header Authorization mit dem Schema Bearer:

HTTP-Header

Authorization: Bearer tmk_live_…

Ein API-Key beginnt immer mit tmk_live_, gefolgt von 43 Zeichen aus Buchstaben, Ziffern, - und _. Andere Übergabewege, etwa als Abfrageparameter in der URL, gibt es nicht. Fehlt der Header, ist der Key ungültig oder wurde er widerrufen, antwortet die API mit 401 und dem Fehlercode unauthorized.

Für Server und Skripte gedacht

Die API setzt keine Cookies und sendet keine CORS-Header. Aufrufe direkt aus dem Browser, etwa aus dem JavaScript einer Webseite, sind daher nicht vorgesehen. Rufe die API von einem Server, einem geplanten Skript oder deinem Lohn- bzw. BI-System aus auf.

Behandle den Key wie ein Passwort. Wer ihn kennt, kann im Rahmen seiner Berechtigungen die Daten deines Standorts lesen. Bewahre ihn deshalb nicht im Quellcode oder in geteilten Dokumenten auf, sondern zum Beispiel in einem Passwort-Manager oder in den geschützten Umgebungsvariablen deines Systems. Lege für jedes angebundene System einen eigenen Key an – dann kannst du einen einzelnen Zugang widerrufen, ohne die anderen zu unterbrechen. TimeMonkey selbst speichert den Key nicht im Klartext.

Scopes

Beim Anlegen eines Keys wählst du unter Berechtigungen (nur lesend) aus, welche Daten er abrufen darf. Jede Berechtigung entspricht einem Scope:

Scope	Berechtigung in TimeMonkey	Endpunkte
employees:read	Mitarbeiter	GET /api/v1/employees, GET /api/v1/employees/{id}
stamps:read	Stempel	GET /api/v1/stamps
absences:read	Abwesenheiten	GET /api/v1/absences
shifts:read	Schichten & Bereiche	GET /api/v1/shifts, GET /api/v1/areas
evaluations:read	Auswertungen	GET /api/v1/evaluations/days, GET /api/v1/evaluations/months, GET /api/v1/evaluations/years

Ohne eigenen Scope kommen aus:

• GET /api/v1/company – funktioniert mit jedem gültigen API-Key.
• GET /api/v1/openapi.json – braucht gar keinen API-Key.

Fehlt einem Key der nötige Scope, antwortet die API mit 403 und dem Fehlercode forbidden_scope. Im Feld details.requiredScope steht der fehlende Scope:

403 Forbidden

{
  "error": {
    "code": "forbidden_scope",
    "message": "Dem API-Key fehlt die Berechtigung stamps:read",
    "details": {"requiredScope": "stamps:read"}
  }
}

Nur die Berechtigungen vergeben, die das System wirklich braucht

Stempel, Abwesenheiten, Schichten und Auswertungen verweisen auf Mitarbeiter nur über deren ID (employeeId). Namen und Vertragswerte liefert ausschließlich GET /api/v1/employees mit dem Scope employees:read. Braucht dein System die Namen, wähle also zusätzlich Mitarbeiter aus.

Die Berechtigungen eines bestehenden Keys lassen sich nicht ändern. Lege bei Bedarf einen neuen Key an und widerrufe den alten.

Zugangsvoraussetzungen

Bei jedem Request prüft die API nacheinander:

1. Ist der API-Key gültig und nicht widerrufen? Sonst 401 unauthorized.
2. Wird der Standort gerade geprüft? Dann 403 company_pending_review.
3. Ist der Zugang wegen einer offenen Zahlung gesperrt? Dann 403 payment_locked.
4. Hat der Standort TimeMonkey Pro oder läuft die Testphase? Sonst 403 license_required.
5. Hat der Key den nötigen Scope? Sonst 403 forbidden_scope.
6. Ist das Rate-Limit noch nicht erreicht? Sonst 429 rate_limited (siehe Fehler und Rate-Limits).

Die API speichert das Ergebnis dieser Prüfungen nicht zwischen. Ein Widerruf, das Ende der Lizenz oder eine beglichene Zahlung wirken deshalb ab dem nächsten Request.

Lizenz und Testphase

Die REST-API ist in TimeMonkey Pro enthalten. Während der 14-tägigen Testphase eines neuen Standorts kannst du sie ebenfalls nutzen. Die Testphase umfasst 14 Kalendertage nach deutscher Zeit (Europe/Berlin).

Endet die Testphase ohne Lizenz, lehnt die API jeden Request mit license_required ab. Die angelegten Keys bleiben bestehen und funktionieren wieder, sobald TimeMonkey Pro lizenziert ist. Wie du lizenzierst, steht unter Lizenz und Rechnungen.

Zahlungssperre

Ist eine Zahlung fehlgeschlagen und die Frist zum Begleichen abgelaufen, ist der Zugang gesperrt, solange keine Zahlung in Bearbeitung ist. Die API antwortet dann mit payment_locked. Die offene Rechnung lässt sich in TimeMonkey begleichen; danach funktioniert die API wieder.

Prüfung des Standorts

Befindet sich ein Standort in einer manuellen Prüfung durch das TimeMonkey-Team, ist die API für ihn gesperrt und antwortet mit company_pending_review. Wende dich in diesem Fall an den Support.