API Keys
Let your organization's own systems read Z8 data through the Public API
An API key lets your own systems, such as payroll, BI or HR tools, read your organization's data through the Public API. The API is read-only.
Who owns a key
An API key belongs to your organization, not to the admin who created it:
- Every owner and admin of the organization sees and manages all of its keys.
- The key list names the admin who created each key. When that person leaves the organization, the key keeps working and the list marks the creator as departed.
- A key stops working only when an admin revokes or disables it, or when it expires.
An organization can have at most 10 API keys.
Create a key
- Go to Settings → Enterprise → API Keys and select Create Key.
- Enter a name, choose an expiration and the permissions (key scopes) the key needs.
- Optionally set the key's rate limit: the maximum number of requests per second, minute or hour.
- Copy the key. It starts with
z8_organd is shown only once.
Keep keys secret
A key reads your organization's data within its scopes. Store it in your integration's secret store, never in client-side code or a public repository.
Key scopes
| Scope | Grants |
|---|---|
time-entries:read | Work periods: recorded work in its current, corrected state |
absences:read | Approved and pending absences |
absences:read-health | Health detail of absences: sick absences with their category and sick detail |
employees:read | Employees (no contract, salary, address or birthday) |
projects:read | Projects |
customers:read | Customers |
custom-fields:read-restricted | Restricted custom fields: the employee, project and customer custom fields only managers or admins see |
Without absences:read-health, a sick absence is returned as plain absent, with no category and no sick detail. Grant the health scope only to integrations that need it.
employees:read, projects:read and customers:read also read that record kind's custom fields, but only those every member can see (visibility Employee). Keys created before custom fields reached the API read them too.
Restricted custom fields
custom-fields:read-restricted adds the custom fields with visibility Manager or Admin, such as salary bands, to every employee, project and customer the key can read, together with their names in the field lists. Grant it only to integrations that need those fields. On its own it grants nothing: the key still needs the matching read scope.
Call the API
Send the key as a Bearer token. The API accepts no browser sessions.
curl https://ui.z8-time.app/api/v1/employees \
-H "Authorization: Bearer z8_org…"Use the address you sign in to Z8 at. Every endpoint, its parameters and its responses are in the API reference. The OpenAPI document is at /api/v1/openapi.json.
Employees, projects and customers carry their custom field values in customFields, keyed by field id. The values are read as of asOf, today in your organization's timezone unless you pass a date. To list the fields themselves, call the record kind's custom-fields endpoint:
curl "https://ui.z8-time.app/api/v1/employees?asOf=2026-07-01" \
-H "Authorization: Bearer z8_org…"
curl https://ui.z8-time.app/api/v1/employees/custom-fields \
-H "Authorization: Bearer z8_org…"Rate limits
Each request counts against the key's own limit and against a limit for your whole organization. Every response to a request with a known key, refusals included, carries:
X-RateLimit-Limit: requests allowed in the current window of the tighter limit.X-RateLimit-Remaining: requests left in that window.X-RateLimit-Reset: when the window resets, in Unix epoch seconds.
When a limit is used up, the API answers 429 with a Retry-After header in seconds.
Recent requests
Select a key's name to open its detail page. It lists the key's recent requests: when, the channel (API for the Public API, MCP for a tool call through the MCP server), which endpoint, the response status, the number of rows returned and the caller's IP address. Requests are kept for 90 days.
Creating, editing and revoking a key are recorded in the organization's audit log (Settings → Enterprise → Audit Log) with the admin who did it.
Revoke a key
Open the key's menu in the key list and select Delete. Applications using the key lose access immediately. To pause a key instead, edit it and turn Key Enabled off.
Errors
Errors are application/problem+json documents with a stable type:
| Status | type | Meaning |
|---|---|---|
| 400 | validation_failed | A query parameter is missing or invalid |
| 401 | invalid_key | The key is missing, unknown, revoked, disabled or expired |
| 402 | billing_required | The organization's subscription does not allow API access |
| 403 | scope_missing | The key lacks the endpoint's scope |
| 404 | not_found | No such endpoint |
| 429 | rate_limited | The key's or the organization's limit is used up |