Access scopes
A scope is what a specific API key is allowed to read. Scopes are coarse-grained (per resource, not per field) and, without exception, read-only — /api/v1 doesn't write data in v1.
The hard rule
A scope unlocks exactly the data the user who created the key would see themselves in the Smengo app. The API doesn't grant access to data hidden from that user by their permissions — in other words, a key's scopes are always a subset of its creator's permissions. If the employee creating the key can't see timesheets themselves, they can't grant the key timesheets.read, even if they try — this is enforced on the server when the key is created.
Scope table
| Scope | Permission required from the key's creator | What it unlocks |
|---|---|---|
employees.read |
"Manage employees" | GET /employees |
schedule.read |
"View schedule" | GET /schedule-entries |
checkins.read |
"Manage employees" | GET /check-ins |
timesheets.read |
"Timesheets" | GET /timesheets |
demand.read |
"Manage shifts" | GET /demand-signals — includes revenue data |
The permission in the right column is the same one that gates viewing this data in the Smengo app itself (Settings → Roles): if a user doesn't have access to the Timesheets section in the UI, they can't create a key with the timesheets.read scope.
Reference resources without a scope
Some resources contain no secrets and are available to any valid key for the organization, regardless of its scopes:
GET /orgGET /departmentsGET /shift-presetsGET /status-types
These endpoints are needed to interpret the rest of the data (for example, to look up a department's name from the department_id returned by /employees), so they're open with no additional conditions.
What happens without the required scope
If a key doesn't have the scope an endpoint requires, the response is 403 missing_scope. The specific scope needed is in the error body's hint. See Error codes for the full error format.
Only one scope is live today
As of this version, only employees.read (GET /employees) is wired up in v1 — the other resources in the table above (schedule.read, checkins.read, timesheets.read, demand.read) will ship as separate endpoints as they become available. The table already describes the final permission model, so integrations can plan ahead for which permission a key owner will need.
What's next
- Authentication — how a key is issued and who can create one.
- Conventions — response format and filters.
- Error codes — what to do about
403 missing_scope.