Integrations

An integration is one of your own systems (a lab interface, a records sync, a reporting job) calling the Nightingale API directly. It signs in as a machine user: an account that belongs to your organization but is not a person. A machine user proves who it is with a token, a long secret your system sends with every request.

The Integrations screen lists your organization’s machine users and their tokens, and is where you create, pause and remove them.

Integrations need the Integrations add-on on your organization’s licence (see Plans and add-ons). Without it the screen only says so, and the API refuses integration requests. Contact support to add it.

Grant the permissions first

Viewing and managing integrations each need their own permission. New organizations have both in the Administrator role, but organizations created before these permissions existed do not: someone who manages roles must add them (see Roles) before anyone can open the screen. Nightingale support can see your integrations but cannot change them, so grant the permissions before you need to replace a token.

How an integration acts

Every request an integration makes names one of your users, and is allowed exactly what that user is allowed. It does not have permissions of its own. So an integration that records lab results should act as a user whose roles let them record lab results.

Your system sends three headers with each request:

Header	Value
Authorization	Bearer followed by the token
X-Client-Type	integration
X-Impersonate-User	the ID of the user it acts as

Everything it does is recorded in the audit log under that user, together with the machine user it came from.

The list

Each machine user shows its name, its ID, which users it may act as (see below) and its tokens. For each token you see:

• Active or Inactive.
• A warning if the token no longer exists at the sign-in provider, for example because it expired. Such a token cannot be used.
• When it expires, or No expiry.

Creating a token

Choose Create Token, then either:

• Create New User to set up a new integration: give the machine user a name you will recognise, such as “Lab interface”. It starts able to act as any of your users.
• Use Existing User to give an existing machine user another token.

You can set an expiry date, or leave it blank for a token that does not expire. Each machine user also has a New token button that does the same for that machine user.

The token is shown once

After the token is created, its value is shown with a copy button. Copy it into your system straight away. It is never shown again, and no one, including support, can retrieve it later. If it is lost, create a new token and delete the old one.

Replacing a token

To rotate a token without downtime, create a new token for the same machine user, switch your system to it, then delete the old one.

Pausing and removing

From a token’s menu:

• Deactivate marks the token inactive, and Activate makes it active again. A machine user can use the API while at least one of its tokens is active, so to pause an integration, deactivate all its tokens.
• Delete Token removes the token for good. It stops working at once. This is the way to stop one particular token while the machine user’s others keep working.

A paused machine user (one whose tokens are all inactive) cannot be given a new token, because the new token would make its old tokens work again, including one you paused because it leaked. Activate one of its tokens first, or, if none of them can be trusted, create a new machine user and delete the old one.

A machine user always keeps at least one token, so Delete Token is unavailable on its only token. To remove that one, delete the machine user.

The bin icon next to a machine user deletes it, with all its tokens and its list of users. Integrations using it stop working at once. This cannot be undone.

Limiting who it can act as

A new machine user may act as any user of your organization. Choose Manage Permissions to change that:

• Full access: it may act as any user.
• Access from list: it may act only as the users you tick. A request naming anyone else is refused.

Switching back to full access keeps the list, so switching to the list again restores it. Only active users can be ticked: if someone on the list has since been deactivated, the dialog says so and removes them from the list when you save it. Changes apply to the integration’s next request.

A good practice is to create a dedicated user for each integration, give that user only the roles the integration needs, and allow only that user.

Who sees what

Viewing the screen needs the permission to view integrations. Creating, pausing and deleting tokens and machine users, and choosing who they may act as, need the permission to manage integrations, which also lets you see your organization’s users.

Managing integrations is powerful

Someone who manages integrations can create a token that acts as any user, including administrators. Grant that permission only to people you would trust with administrator access.

An integration itself can never change integrations, even when it acts as someone who manages them: it can list machine users and tokens, but creating, pausing or deleting them, or changing who they may act as, must be done by a person signed in to Nightingale. So a machine user limited to a list of users cannot lift that limit, or create a new token, on its own.

Nightingale support can see your integrations but does not change them.