Scopes
What each scope lets a key read, and which fields need people:read.
A key's scopes decide which registers it reads. The company owner or admin picks them when they create the key; give each integration only the scopes it needs.
| Scope | In Works Studio | Reads | Endpoints |
|---|---|---|---|
training:read | Training records | Training records, at a moment and over a period, and the courses they refer to. | /v1/training-records, /v1/training-records/period, /v1/courses |
certificates:read | Certificate records | Certificates and their state at a moment. | /v1/certificates |
people:read | Names and work emails | The people register, and names, work emails and check codes in the other registers. | /v1/people |
/v1/snapshot works with any scope, because it returns only sequence numbers and times.
Names, work emails and check codes need people:read
people:read also controls identity fields in the other registers. Without it:
- training records leave out
person_nameandwork_email; - certificate records leave out
person_nameandcheck_code.
Person IDs, dates and status stay in every record, so an integration without people:read still joins records to its own roster by ID.
A certificate's check code opens a public page that shows the holder's name, so it needs the same permission as the name.
When a scope is missing
A call to a register the key has no scope for answers insufficient_scope with status 403. The WWW-Authenticate header names the scope it needs. Retrying with the same key gives the same answer; ask the company administrator for a key with that scope.