Integration API | MASK docs

The MASK Integration API lets your own systems work with MASK without a person signing in. It is built for three jobs:

Pull attendance into payroll or HR: clock events, shifts, and the monthly payroll totals.
Push employee master data from your HR system: new people, changes, the start and end of employment.
Push clock events from a system of your own, such as an access-controlled gate.

It is a JSON API over HTTPS, versioned as v1, and every request authenticates with an API key that your MASK administrator issues.

Base URL#

Every MASK system has its own address, and the API lives under /api/v1/integration/ on it. Your administrator gives you the address together with the key.

https://<your MASK address>/api/v1/integration/

The examples on this site use two shell variables:

MASK=https://<your MASK address>/api/v1
KEY=tna_api_…          # the key your administrator gave you

Your first request#

GET /integration/key answers with what the calling key may do, which makes it the first call to try with a new key:

curl -s "$MASK/integration/key" -H "Authorization: Bearer $KEY"

{
  "id": 26,
  "name": "Docs example: payroll pull (Docs Example School)",
  "scopes": ["employees:read", "cards:read", "events:read", "sessions:read", "reports:read"],
  "allInstitutions": false,
  "institutionIds": [1],
  "rateLimitPerMinute": 120
}

The examples in these guides and in the reference are real answers from a MASK test system. The names in them are made up: the institution Docs Example School (id 1, the one most examples use), a second institution (id 4) and the employee Ana Primjer (id 24). Keys are shortened to tna_api_….

What you can reach#

Resource	Read	Write	Scopes
Reference data: the key, its institutions, the event catalog	Yes	No	any key
Employees and their memberships	Yes	Create, update, add, end and reactivate memberships	`employees:read`, `employees:write`
Cards	Yes	No	`cards:read`
Clock events	Yes	Create, correct, void	`events:read`, `events:write`
Sessions (shifts)	Yes	No, they follow from the events	`sessions:read`
Reports: per institution, payroll month, per employee	Yes	No	`reports:read`

There are no card writes, no absence endpoints and no webhooks in v1: your system pulls on its own schedule. Recommended sync flows shows how.

Getting a key#

Your MASK administrator creates the key on the API Keys page of the MASK web app. They choose:

a name, so the key is recognisable on the API Keys page;
the access, as one of the presets Read everything and Read + write everything, or per resource;
the institutions the key covers, or all of them, including institutions created later;
optionally an expiry date, an IP allowlist and a rate limit.

The key is shown once. If it is lost, the administrator replaces it with a new one. Read Authentication next.

The OpenAPI document#

mask-integration-api-v1.json is the machine-readable contract: every route, parameter, body and answer, the errors and the response headers included, and the scope each route needs. It is generated from the running code, so it always matches what the server answers. Import it into Postman, Insomnia or a client generator, and set its server variable host to your MASK address.

Support#

Write to dev@mask.ba. Quote the key's prefix (its first 16 characters, such as tna_api_Q7vK2mXe), never the key itself, and the X-Request-Id of the request in question: every answer carries one.