InnerWeb
Skip to main content

FAQ: person API for a portal, covering training and access passes

The person API lets a portal fetch from the plant a person's list of trainings with status, a personal link to training and an access pass. Everything works behind a machine token, and an account deleted in the system returns a 404 response. Below we answer the questions of integrators and IT managers who plan to connect a contractor or employee portal to the plant.

4
training statuses in the API response
Source: feature card
30 days
window for the expiring training status
Source: feature card
7 days
period for counting errors in the panel
Source: feature card

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

Response codes for access requestsThe chart shows four API response codes for access requests: 201, 200, 400 and 401.0100200300400500kod HTTPNew request: 201 kod HTTP201New requestRepeat: 200 kod HTTP200RepeatIncorrect data: 400 kod HTTP400Incorrect dataWrong token: 401 kod HTTP401Wrong token
Source: Feature card of the portal integration

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