Scopes and institutions

A key opens exactly what the administrator granted: some scopes (what it may read or write) over some institutions (which locations' data). This page explains both, and which employees a key can see.

Scopes#

A key carries one or more scopes, one per resource. A request outside them is 403 scope_missing, and the message names the scope (Insufficient scope: events:write). Every operation in the reference shows its scope in its heading.

The web app offers two presets: Read everything (the five :read scopes) and Read + write everything (all seven).

Institutions#

A MASK system holds one or more institutions: the sites, schools or companies whose attendance it records. The administrator gives a key either a list of institutions or all institutions, which includes institutions created later. GET /integration/key says which (allInstitutions, institutionIds), and GET /integration/institutions lists them with their time zone and day boundary.

• A parameter outside the key is a 403, a resource outside the key is a 404. An institutionId= naming an institution the key does not cover is 403 institution_not_allowed. An employee, event, session or institution outside the key is 404 not_found.
• Archived institutions stay readable: they are listed with status: "archived" and their history is in every read. Every write that touches one is 409 conflict.

Which employees a key sees#

• An employee is visible to a key when they have any membership, active or ended, in one of its institutions. Their memberships[] then lists only the memberships in the key's institutions.
• An employee without any membership is invisible to every key, for reads and writes.
• Someone whose membership in institution A has ended is still visible to A's key, and that key sees the person's current email, personalId, status and active card.
• employeeId= naming someone the key cannot see gives an empty list on the list routes (/cards, /events, /sessions) and a 404 on /reports/employee, as an id the key cannot see does on every by-id route.

Writes about people who also work elsewhere#

For a key with a list of institutions, every active membership of a person must lie in the key's institutions before the key may change that person (PATCH /employees/{id} and the membership writes). Otherwise the answer is 403 institution_not_allowed, "Employee has an active membership outside this key's institutions": the administrator of that other institution owns the record. Ended memberships elsewhere do not count, and all-institutions keys are exempt.

The status of some protected employee records cannot be changed through the API (403 admin_linked_employee). Their name, email, personalId and language may still change.