Authentication and scopes
API keys, role and binding, scopes and classified fields.
Developer documentation
API keys
The account owner creates, rotates and revokes keys on the Settings › API screen. A key has a name, a role, a binding, scopes, a validity period and an optional list of allowed IP addresses.
- The full key starts with the
biik_sk_prefix and is shown only once, when it is created. biik does not store the key itself, only a digest to verify it: a lost key cannot be recovered, you create a new one. - The validity is 90 days by default and at most 365 days. An expired key stops working.
- The allowed IP list takes at most 20 addresses or ranges. With an empty list the key works from any address.
- Rotating gives a new key. The old key keeps working during the overlap you choose (24 hours by default, at most 168 hours); if you suspect the key leaked, rotate with "Immediately" or revoke the key.
- Creating and rotating ask for extra verification. Revoking does not and is always available.
- The Request log on the screen shows every call (method, path, status, key). Every write made through the API is recorded in the product's audit log with the key as the actor.
Authenticating a request
The key is sent only in the Authorization header:
Authorization: Bearer biik_sk_...
- A key in the query string gets
400 key_in_query; a key sent together with a cookie gets400 cookie_with_key. - An invalid, expired and revoked key get the same response:
401 unauthorized. Which one it was is not revealed. - The API is not meant to be called from a browser: no CORS headers are returned. Keep the key on the server side.
Role and binding
A role is chosen when the key is created. The role's permissions and its reach (the whole account, one company, one location or one unit) are the widest set the key can see. Scopes only narrow that set, they never widen it.
- A record the key cannot see, a record of another account and a record that does not exist get the same response:
404 not_found. Lists never return rows the key cannot see; the page size and the cursor count only visible rows. - The key keeps working if the person who created it leaves the account; the account owners are notified and the key is marked "Review" in the list.
Scopes
| Scope | Description |
|---|---|
employees:read | Read employees |
employees:write | Create and update employees |
org:read | Read the organisation structure |
leave:read | Read leave |
shifts:read | Read shifts |
events:read | Read the event stream |
health_ | Read duty rosters |
health_ | Write duty pay and bonus data |
field:salary | Salary |
field:national_ | National ID |
field:iban | IBAN |
field:pii | Personal details |
field:health | Health information |
- A resource scope opens that resource's endpoints:
employees:readopens reading employees,employees:writecreating and updating them. A writing endpoint returns the current state of the resource, so it needs the read scope too: forPOST /api/v1/employeesthe key must carryemployees:writeandemployees:readtogether. - An operation outside the key's scopes gets
403 insufficient_scope; an operation the role does not allow gets403 forbidden. events:readis only granted to a role that sees the whole account; events are not filtered per record.
Classified fields
The national ID (national_id), IBAN (iban), salary (salary), personal details (personal) and a leave type hidden in the calendar (health) are classified fields.
- A classified field is returned only when the key carries the matching
field:<class>scope and the role carries the same field class. - If not, even the field name is absent from the response. If the condition holds but there is no value, the field is
null. - Lists carry no classified field; classified fields are returned only by single-record reads. Every read that returns a value is written to the product's access log, with the key as the reader.
- Classified fields cannot be written through the API in this version.