What the person API returns
For a portal, the person API returns three kinds of information: the list of trainings with status, a personal link to training and an access pass. Each of them concerns one person identified in the plant, so the portal does not need to keep its own copy of the authorisation state.
This arrangement keeps responsibilities clear: the source of truth about training and access passes is the plant system, and the portal is only a view. A change of status in the plant is visible in the portal at the next query.
Which training statuses are returned?
Four: todo, done, expiring and expired. The todo status means training still to be completed, done means training passed, expiring means passed but expiring within 30 days, and expired means that the validity of the training has ended.
The expiring status lets the portal show a warning in advance, before the person loses the ability to enter the site.
What is a personal link to training?
It is an address that the API issues for a specific person and a specific training. The portal can display it as a button, and the person completes the training without logging in manually to a separate system.
How the API is secured
All calls to the person API require a machine token. The token is stored on the server side of the portal, and in the plant panel the keys never reach the browser: the integration settings are read-only.
For the integrator this means a simple rule: API calls are made by the portal's backend, never by code running in the user's browser. A token in the page code would be a token exposed to everyone.
What happens when the token is wrong?
The call is rejected. In the analogous API for access requests, a missing or wrong token gives a 401 response. The integrator should treat 401 as a signal to check the configuration, not as a reason to retry in a loop.
Can the token belong to an ordinary employee account?
It should not. The machine token is intended for the integration, has a limited scope, and its use can be told apart from human actions in the exchange log. Recommendations for a technical account are described in a separate material on permissions.
Response codes for access requests
Errors and edge cases
An account deleted in the system returns a 404 response. The portal should treat 404 as information that the person does not exist in the plant, and remove or mark the link on its side, instead of displaying old data.
The exchange log on the plant side records events with direction, result and HTTP code, and writing to the log never interrupts handling of a request. When diagnosing a problem, the integrator can therefore compare its own logs with the plant log.
How do you tell a person with no trainings from a deleted person?
A person with no trainings receives a correct response with an empty or short list, while a deleted person receives a 404. This way the portal does not confuse a lack of data with a lack of an account.
What about access requests submitted by the portal?
An access request arrives in a separate POST call with the machine token. A 201 response means a new request, 200 a repeat of the same request identifier, 400 incorrect data, and 401 a missing or wrong token. Data on authorisations, trainings and medical examinations is accepted only when the scope of the person's consent covers it.
The role of the administrator and the operator
The integration panel in the permissions module shows the connection status, the number of active passes, linked accounts, requests waiting for a decision and errors from the last 7 days, together with the exchange log. The panel is visible to the administrator and the OHS specialist.
Accepting, rejecting and retrying decisions on access requests from the portal is available only to the service administrator role. The division protects against a situation in which a person with view-only rights changes access decisions.
What about a decision that could not be delivered?
An undelivered decision stays in a row with the error description and can be retried from the panel. The operator therefore does not have to ask the integrator to rebuild the request manually.
Video
Frequently asked questions
Does the portal have to keep a copy of the trainings?
No. The state comes from the plant, and the portal fetches it at query time. Its own copy is needed only as a cache.
How often should the person API be queried?
When the person opens the portal page, not in a background loop. The expiring status has a 30-day window, so refreshing once per visit is enough.
What should the portal do when it gets a 404 for a known person?
The account has been deleted in the plant. Mark the link as outdated and direct the person to submit a new access request.
Does the API return data the person did not consent to?
Data on authorisations, trainings and medical examinations is accepted in requests only when the scope of consent covers it.
Connect the portal to the plant
We will show a query to the person API on test data and discuss how the contractor portal should display training statuses. Book a meeting with InnerWeb.
Let's talk