Scopes

Jede Operation verlangt genau einen Scope, benannt als <resource>.<action>:

shifts.read        locations.write        timesheets.read

• GET verlangt .read.

• POST, PATCH, DELETE verlangen .write.

• Schreiben schliesst Lesen ein — shifts.write erfüllt auch shifts.read, du musst also nie beide anfordern.

Der Katalog

Die Menge der erteilbaren Scopes ist geschlossen und Teil des Vertrags. Hier ist sie vollständig — eine Zeile je Ressource, jeweils mit ihrem .read- und .write-Scope:

Scopes	Deckt ab
account.read · account.write	Mandanteneinstellungen (Singleton).
areas.read · areas.write	Bereiche innerhalb eines Standorts.
availability.read · availability.write	Verfügbarkeitsblöcke von Mitarbeitenden (inkl. wiederkehrender).
break_rules.read · break_rules.write	Definitionen von Pausenregeln.
budgets.read · budgets.write	Personalbudgets und Umsatzziele.
employees.read · employees.write	Mitarbeitende, ihre Mitgliedschaften, Einladungen und ihr Lebenszyklus.
employment_types.read · employment_types.write	Anstellungsarten und ihre Lohnvorgaben.
events.read · events.write	Allgemeine Termine (ausser Schichten) und ihre Teilnehmenden.
holidays.read · holidays.write	Feiertagskalender.
labor_cost.read	Personalkostenbericht.
leave_balances.read	Abwesenheitssalden (nur lesbar).
leave_policies.read · leave_policies.write	Abwesenheitsrichtlinien und ihre Stufenleitern.
leave_requests.read · leave_requests.write	Abwesenheitsanträge und ihre Prüfübergänge.
locations.read · locations.write	Standorte.
open_shifts.read	Angebote für offene Schichten (auf dieser API nur lesbar).
positions.read · positions.write	Positionen, ihre erwarteten Qualifikationen und die Zuteilung von Mitarbeitenden.
shifts.read · shifts.write	Schichten, ihr Veröffentlichungsstand und ihre Zuteilungen.
skills.read · skills.write	Qualifikationskatalog.
swaps.read	Angebote für Schichttausche (auf dieser API nur lesbar).
time_compensation.read · time_compensation.write	Journal und Salden der Zeitgutschrift.
timesheets.read · timesheets.write	Stundenrapporte, Zeitstempel, Pausen und Freigaben.
webhook_endpoints.read · webhook_endpoints.write	Registrierung von Webhook-Endpunkten und Rotation der Geheimnisse.
webhook_log.read	Verlauf der ausgelieferten Ereignisse zum Abgleich.
work_rules.read · work_rules.write	Arbeitsregeln (inkl. des Blocks zur Zeitgutschrift nach Art. 17b).

Für einen einzelnen Endpunkt brauchst du diese Tabelle nicht: jede Operation in der API-Referenz nennt direkt den Scope, den sie verlangt. Sowohl diese Angabe als auch die Tabelle oben stammen aus demselben Wert, den die Berechtigungsprüfung des Servers liest — was dokumentiert ist und was durchgesetzt wird, kann also nicht auseinanderlaufen.

Die richtigen anfordern

Scopes werden je Anbindungs-Client erteilt, wenn wir ihn registrieren — frag also nach dem, was die Anbindung tatsächlich tut, und nach nicht mehr. Ein Lohnexport, der Stunden liest, bekommt timesheets.read und sonst nichts.

Ein Tippfehler fällt schon bei der Registrierung auf, nicht zur Laufzeit: shift.read wird mit einem Vorschlag abgelehnt, statt einen Client zu registrieren, der bei jedem Aufruf scheitert.

Um später einen Scope zu ergänzen, schreib an support@shiftavo.com — dafür braucht es keine neuen Zugangsdaten.

Wenn ein Scope fehlt

Ein Aufruf mit gültigem Token, aber ohne die nötige Berechtigung ist:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "…",
    "details": []
  }
}

mit Status 403. Das ist etwas anderes als ein 401 (das Token selbst taugt nichts — siehe Authentifizierung) und als ein 404, den du auch für einen Datensatz ausserhalb deines Unternehmens bekommst, damit dessen Existenz nie durchsickert.