Scopes & modules

Access on the public API is governed by two independent gates. Both must pass for a request to succeed.

Scopes

A scope is a permission granted to an API key, named <resource>:<action> (e.g. users:read). Scopes are chosen when the key is created and can be edited later by an administrator.

Every endpoint documents the scope it requires. Calling an endpoint without the scope returns:

{
  "error": {
    "code": "forbidden",
    "message": "API key is missing the required scope: users:read",
    "status": 403
  }
}

Grant the minimum set of scopes the integration needs — you can always add more later without touching the key itself.

Current scope catalog

Scope	Module	Description
`company:read`	Core	Read the authenticated tenant's own company profile.
`users:read`	Core	Read the company's users (directory data only).
`users:write`	Core	Provision users: create, deactivate and reactivate.
`employees:read`	Core	Read the company's employees (HR profile, no payroll).
`roles:read`	Core	Read the company's roles and their permissions.
`projects:read`	Projects	Read the company's projects (registry data, no commercial details).
`shifts:read`	Projects	Read the company's work shifts.
`absences:read`	Projects	Read the company's absences (leave requests).
`expenses:read`	Projects	Read the company's project expenses.

The catalog grows with every release — see the changelog.

Modules

Onwork companies activate modules (Projects, Expenses, CRM, …). Each scope belongs to a module: if the backing module is not active for the company, the scope is inert — granting it is blocked in the admin UI, and using an already-granted scope after a module is deactivated returns 403.

Additionally, the Public API module itself is the master switch: if an administrator deactivates it, every key of the company stops authenticating (403) until it is reactivated.