Scopes

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

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.

Jede Operation in der API-Referenz nennt direkt den Scope, den sie verlangt. Diese Angabe stammt 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 Integrations-Client erteilt, wenn wir ihn registrieren — frag also nach dem, was die Integration 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 dem Support — 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.