Public API

API Roles & Scopes

How scopes limit what a token can reach, how reusable API roles and the built-in templates work, and the full scope catalogue with the minimum owner role for each scope.

A token's access is the overlap of three things, worked out again on every request:

The scopes it was granted, either through an API role or as a custom list.
The ceiling of its owner's current role. Each scope has a minimum owner role; scopes above the owner's role are ignored.
The scopes that have endpoints today. A scope only takes effect once at least one endpoint uses it.

Inside a scope, the data returned is always limited to what the owner can see in the app. A scope opens an area of the API; it never widens the owner's own visibility.

GET /token returns the resulting effective scopes, so an integration can check what it may do before it starts.

Scope naming

Scopes are written resource:action, for example leaves:read or leaves:approve.
A . marks a more sensitive tier of a resource's fields, for example users.personal:read on top of users:read.
A write scope also satisfies the matching read scope for the same resource and tier. leaves:write lets a token call endpoints that need leaves:read; it does not satisfy leaves:approve, and users:write does not satisfy users.personal:read.

When a token calls an endpoint without the scope it needs, the response is 403 SCOPE_MISSING, and the message names the scope that endpoint requires. Each operation in the API Reference lists its required scope.

API roles

An API role is a named, reusable set of scopes, such as "Payroll export" or "Leave dashboard". Administrators and Executives manage them on the API roles tab under Settings > API.

A token created from a role follows it. Editing the role changes every token that uses it, from the next request.
Archiving a role makes every token that follows it grant nothing until the role is restored. Roles are never deleted.
A role can only contain scopes the person creating or editing it may hold. An Administrator cannot define a role with Executive-only scopes.
A token can only follow a role whose scopes are all within its owner's role ceiling.

A token can instead have a custom scope list, which is fixed to that token.

Built-in templates

Templates are starting points for a new API role or a custom token. When applied, a template keeps only the scopes that have endpoints today and that the owner's role may hold.

Template	Scopes
Read-only directory	`organization:read`, `users:read`, `departments:read`, `teams:read`
Leave sync	`organization:read`, `users:read`, `leave_types:read`, `leaves:read`, `leave_balances:read`, `holidays:read`
Leave management	Everything in Leave sync, plus `leaves:write` and `leaves:approve`
Time and payroll export	`organization:read`, `users:read`, `users.employment:read`, `time_entries:read`, `timesheets:read`, `projects:read`
HRIS sync	Every `read` scope except `compensation:read`, `users.govid:read` and `webhooks:read`

HRIS sync includes sensitive read scopes, such as users.personal:read, time_entries.location:read, documents.content:read and benefits:read, when its owner's role allows them. Review the list before saving, and remove anything the receiving system does not need.

Scope catalogue

The minimum owner role is the lowest role whose tokens may hold the scope. The four roles, from lowest to highest, are Employee, Department Head, Administrator and Executive.

Scopes marked Sensitive read restricted personal, financial or file data and are flagged in the token console.

Scope	Minimum owner role	Grants	Sensitive
`organization:read`	Employee	Read the organization profile
`users:read`	Employee	Read the employee directory
`users.employment:read`	Department Head	Read employment details (dates, probation, payroll id)
`users.personal:read`	Administrator	Read personal details (date of birth, home address, emergency contact)	Yes
`users.govid:read`	Executive	Read government identifiers	Yes
`users:write`	Administrator	Create and update employees
`departments:read`	Employee	Read departments
`departments:write`	Administrator	Create and update departments
`teams:read`	Employee	Read teams
`teams:write`	Administrator	Create and update teams
`leave_types:read`	Employee	Read leave types
`leaves:read`	Employee	Read leave requests
`leaves:write`	Employee	Create and cancel leave requests
`leaves:approve`	Department Head	Approve and reject leave requests
`leave_balances:read`	Employee	Read leave balances
`holidays:read`	Employee	Read public holidays and locked dates
`time_entries:read`	Employee	Read time entries
`time_entries:write`	Employee	Create, update and delete time entries
`time_entries.location:read`	Administrator	Read clock-in and clock-out locations	Yes
`time_entries:approve`	Department Head	Approve and reject time entries
`timesheets:read`	Employee	Read timesheets
`projects:read`	Employee	Read projects, tasks and clients
`schedules:read`	Employee	Read shift schedules
`expenses:read`	Employee	Read expense reports
`expenses:approve`	Department Head	Approve and reject expense reports
`documents:read`	Employee	Read document metadata
`documents.content:read`	Administrator	Download document files	Yes
`training:read`	Employee	Read training assignments
`training:write`	Department Head	Assign training
`certifications:read`	Employee	Read certifications
`assets:read`	Employee	Read assigned assets
`assets:write`	Department Head	Assign and update assets
`benefits:read`	Administrator	Read benefit enrollments	Yes
`compensation:read`	Administrator	Read compensation records	Yes
`onboarding:read`	Employee	Read onboarding progress
`custom_fields:read`	Employee	Read custom profile fields
`goals:read`	Employee	Read goals
`webhooks:read`	Administrator	Read webhook endpoints, deliveries and the event catalogue
`webhooks:write`	Administrator	Create, update, test and delete webhook endpoints

Every scope in the catalogue has at least one endpoint. Each operation in the API Reference names the scope it requires, and the OpenAPI document carries it as x-required-scope. Operations that return more fields with a field-tier scope, such as users.personal:read on GET /users, list those scopes in x-field-scopes.

Field tiers

A field-tier scope adds fields to responses the base scope already opens; it never opens an endpoint on its own.

Base scope	Field-tier scope	Adds
`users:read`	`users.employment:read`	Employee and payroll ids, employment type, employment start and end dates, probation, offboarding date
`users:read`	`users.personal:read`	Date of birth, gender, marital status, nationality, personal phone numbers and email, home address, emergency contact
`users:read`	`users.govid:read`	Tax id, citizenship certificate number, benefit id number
`time_entries:read`	`time_entries.location:read`	Clock-in and clock-out coordinates, addresses and accuracy, location confidence, whether the clock-in was outside the geofence
`timesheets:read`	`users.employment:read`	Pay figures, for Administrator and Executive owners only

Reads that return users.personal:read, users.govid:read, compensation:read or documents.content:read data are written to the organization's sensitive-data access log, one entry per record, with the token that read them.

Rules beyond the scope

A scope is necessary but not always enough: the owner must also be allowed to do the same thing in the app. The cases that most often surprise integrators:

Endpoint	Rule
`GET /clients`	Department Heads and above. An Employee's token gets `403 FORBIDDEN` even with `projects:read`.
`GET /users/{id}/custom-fields`	The owner's own values, or anyone's for an Administrator or Executive. Other people answer `404`.
Approving or rejecting leave, time entries and expense reports	Nobody decides their own request through the API, whatever their role (`403 FORBIDDEN`). A Department Head decides only inside their own and managed departments. A record the owner cannot see answers `404`; a leave request they can see but may not decide answers `403 FORBIDDEN` before anything is revealed about its state.
`POST /leaves` for someone else	Administrators and Executives, or the person's Department Head.
`PATCH /users/{id}`	Only an Executive edits or promotes to Executive, and nobody changes their own role.
Webhook endpoints	Owners must be Administrators or Executives, whatever Who may create tokens allows.

The guides describe the visibility rules for each area.

Choosing scopes

Start from the narrowest template that fits, then remove anything unused.
Use separate tokens for separate integrations rather than one token with every scope.
Prefer read scopes for reporting and sync jobs. Grant write or approve only to integrations that genuinely act on behalf of their owner.
Give sensitive scopes only to tokens owned by someone whose job already involves that data, and pair them with an IP allowlist.

Authentication & Tokens

How API tokens are formatted and sent, how expiry, rotation and revocation work, IP allowlists, what stops a token, and how to store one safely.

Requests & Responses

The response envelope, field naming, calendar dates and timestamps, cursor pagination, request bodies, idempotency keys and request ids.