Scopes

Every operation requires exactly one scope, named <resource>.<action>:

shifts.read        locations.write        timesheets.read

• GET requires .read.

• POST, PATCH, DELETE require .write.

• Write implies read — shifts.write also satisfies shifts.read, so you never need to request both.

The catalog

The grantable set is closed and shipped as part of the contract. Here it is in full — one row per resource, each with its .read and .write scope:

Scopes	Covers
account.read · account.write	Tenant settings (singleton).
areas.read · areas.write	Areas within a location.
availability.read · availability.write	Employee availability blocks (incl. recurring).
break_rules.read · break_rules.write	Break rule definitions.
budgets.read · budgets.write	Labor budgets and revenue targets.
employees.read · employees.write	Employees, their memberships, invites and lifecycle.
employment_types.read · employment_types.write	Employment types and their payroll defaults.
events.read · events.write	General (non-shift) events and their attendees.
holidays.read · holidays.write	Public-holiday calendar.
labor_cost.read	Labor-cost report.
leave_balances.read	Leave balances (read-only).
leave_policies.read · leave_policies.write	Leave policies and their tier ladders.
leave_requests.read · leave_requests.write	Leave requests and their review transitions.
locations.read · locations.write	Locations.
open_shifts.read	Open-shift offers (read-only on this API).
positions.read · positions.write	Positions, their skill expectations and employee assignments.
shifts.read · shifts.write	Shifts, their publication state and assignments.
skills.read · skills.write	Skill catalog.
swaps.read	Shift swap offers (read-only on this API).
time_compensation.read · time_compensation.write	Time-compensation ledger and balances.
timesheets.read · timesheets.write	Timesheets, clock stamps, breaks and approvals.
webhook_endpoints.read · webhook_endpoints.write	Webhook endpoint registration and secret rotation.
webhook_log.read	Dispatched-event history for reconciliation.
work_rules.read · work_rules.write	Work rules (incl. the Art. 17b time-compensation block).

For a single endpoint you don’t need this table: every operation in the API Reference declares the exact scope it requires, right on the operation. Both that requirement and the table above are derived from the same value the server’s permission check reads, so what is documented and what is enforced cannot drift apart.

Asking for the right ones

Scopes are granted per integration client when we register it, so ask for what the integration actually does and nothing more. A payroll export that reads hours gets timesheets.read and nothing else.

A typo is caught at registration, not at runtime: shift.read is refused with a suggestion rather than registering a client that fails on every call.

To add a scope later, email support@shiftavo.com — it does not require new credentials.

When a scope is missing

A call with a valid token but without the required grant is:

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

with status 403. That is distinct from a 401 (the token itself is bad — see Authentication) and from a 404, which is also what you get for a record outside your company, so that existence never leaks.