InnerWeb
Skip to main content

Machine tokens of integrations: recommendations for the administrator

The machine token of the integration with the qualification portal is the key to searching for people, and, when registration from a QR poster is enabled, also to creating accounts and companies and issuing passes. Such a key deserves its own policy: an owner, a scope, rotation and monitoring. Below are recommendations for the IT administrator.

3
minimum number of characters in a search query
Source: karta
8
maximum number of results in a search response
Source: karta

Why a machine token needs separate attention

The API for the qualification portal requires a machine token in the header. A missing or wrong token returns a 401 response, and search queries require at least 3 letters or digits and return at most 8 results. These limits make it hard to browse the whole database of people, but they do not replace the protection of the key itself.

A token does not represent a human, so there is no second factor and no login screen. Whoever holds it uses the integration's permissions. That is why the risk assessment for a token is stricter than for an ordinary account.

Recommendation 1: count the blast radius

When registration from a QR poster is enabled, the same machine token creates accounts and companies and issues passes. Before enabling this function, write down what the token can do in the worst case: how many accounts could be created, which passes issued and which data read.

Enter the result in the plant's IT risk register. If the plant does not need registration from a poster, do not enable it just because it is available: a smaller function means a smaller blast radius.

Limits of the person search query

Limits of the person search queryChart: minimum 3 characters in the query and maximum 8 results in the response02468countMinimum characters in queryMinimum characters in query: 3 count3Maximum results in responseMaximum results in response: 8 count8
Source: Component card: description of the API for the qualification portal

Recommendation 2: keep the key outside the browser and the repository

The system follows the rule that integration keys never leave the browser. The SSO panel shows settings read-only, and accepting, rejecting and repeating a decision on a request is limited to one administrative role. On the plant side, apply the same rule: the key goes into a secrets manager, not into a script, a message or a project document.

  • One owner of the token, named, with a deputy.
  • Storage in a secrets manager, access by role.
  • Ban on sending the token by e-mail or messenger.
  • Rotation on a schedule and after every change of a person with access.

Recommendation 3: separate the roles that accept requests

Decisions on access requests are made by one administrative role. Assign to it a small, named group of people and review it every quarter. Separating the person who manages the token from the person who accepts requests reduces the risk that one account controls the whole chain.

Recommendation 4: monitor the exchange log

The exchange log with the portal records direction, event, person, result, HTTP code and time, and writing to the log never interrupts the main operation. This lets you detect a series of 401 responses, unusual call hours or a sudden rise in search counts.

Set alert thresholds in your monitoring tool and check the log after every token rotation. The correct picture after rotation is a short series of 401 responses from the old key, followed by a stable series of successes.

Recommendation 5: plan rotation without interrupting the service

Schedule rotation outside the peak of contractor entries. Agree with the portal administrator on the moment of replacing the key and on the rollback procedure. After rotation, run a test: a person search, a request submission and a read of the log.

Record the key change and its date in the change register. If a leak is suspected, replace the key immediately and describe the event in the plant's incident log.

Video

Frequently asked questions

What does the API return for a wrong token?

A 401 response. Such an entry appears in the exchange log with the HTTP code, direction and time.

Can the integration key be seen in the panel?

No. Keys never leave the browser, and the SSO panel shows settings read-only.

Who can accept an access request?

Accepting, rejecting and repeating a decision is done by one administrative role, which the plant assigns to selected people.

Let's put the integration keys in order

Together with your IT team we will set out the token's scope, its owner and the rotation plan before the integration goes live in production.

Let's talk