Skip to content

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 gets 400 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

ScopeDescription
employees:readRead employees
employees:writeCreate and update employees
org:readRead the organisation structure
leave:readRead leave
shifts:readRead shifts
events:readRead the event stream
health_scheduling:readRead duty rosters
health_premiums:writeWrite duty pay and bonus data
field:salarySalary
field:national_idNational ID
field:ibanIBAN
field:piiPersonal details
field:healthHealth information
  • A resource scope opens that resource's endpoints: employees:read opens reading employees, employees:write creating and updating them. A writing endpoint returns the current state of the resource, so it needs the read scope too: for POST /api/v1/employees the key must carry employees:write and employees:read together.
  • An operation outside the key's scopes gets 403 insufficient_scope; an operation the role does not allow gets 403 forbidden.
  • events:read is 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.