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.
Note: timesheet rows contain only employee_id, no names — for the typical "timesheet with employee names" report, a key needs employees.read in addition to timesheets.read.
Reference resources without a scope
Some resources contain no secrets and are available to any valid key for the organization, regardless of its scopes:
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.
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.