API docs
Introduction
Authentication
The API uses API keys assigned to a tenant (not to a user). Every request must include a valid key, and the range of operations is limited by the set of permissions (scopes) granted to that key.
API key
You create and revoke keys in the panel, in the /app/settings/api-keys section. A key has the onb_ prefix and its full value is shown only once at the moment of creation — in the database we store only the SHA-256 hash, so the key cannot be read later.
Treat the key like a password
The key grants access to employees' personal data. Store it on the server side (environment variables / secrets), never in front-end code or in a repository. Immediately revoke a suspected key in the panel and generate a new one.Passing the key
You pass the key in a header. Both methods are equivalent — pick one:
Authorization: Bearer onb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Onboardly-Api-Key: onb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxcurl -H "Authorization: Bearer onb_..." \
"https://www.onboardly.work/api/v1/employees?pageSize=50"Scopes
Each key has an assigned set of scopes. Calling an endpoint without the required scope results in a 403 forbidden_scope error. Grant keys according to the principle of least privilege.
| Scope | Grants |
|---|---|
read:employees | read and export employee records |
write:employees | import, update (PATCH), ZUS deregistration |
read:payroll | read payroll and settlements |
read:invoices | read invoices / bills |
Tenant-scope
A key is uniquely tied to a tenant. All resources returned by the API are automatically limited to that tenant's data — there is no way to read another tenant's data, even knowing the resource identifier (such a case returns 404 not_found).
PII access audit
Every read or export of an employee record (with decrypted personal data) writes an audit entry in accordance with art. 30 GDPR. This way it is always known which key accessed sensitive data and when.