How to Pair a Device with an Agent

A paired device is a browser, such as a shared tablet or a ChromeOS kiosk, that stays signed in to a Space's app as one of your organisation's Agents, without anyone entering a password on it. This guide pairs a device, disables it, and lets it back in.

For every state and limit, see Devices.

Prerequisites

An organisation Agent that has joined the Space whose app the device will use. See Agents, or Your First Agent and Paired Device to create one.
Organisation permissions to pair and approve devices. Organisation owners have them.
On the device: an up-to-date Chrome over HTTPS, in a normal (not private or guest) window.
Device pairing enabled for your organisation. If it is not, the Agent page has no Devices section; contact Ligantic support.

Be with the device while you pair it, so you can compare the confirmation on both screens.

Pair a device

In Ligantic, open Organisations → your organisation → Agents, then the Agent.
Under Devices, select Pair a device. A dialog shows an 8-digit pairing code, such as 4829-1305.
The code is shown only once and expires after 10 minutes. You can rename the device later; it starts with a generated name such as brave-teal-otter.
On the device, open the Space's app address followed by /__auth/device, for example https://your-space.example.com/__auth/device.
Enter the pairing code and select Pair this device. The dash is optional. If a digit is mistyped, the page says the code has a typo before sending it; check each digit again.
The device shows a 6-digit confirmation, such as 482 913, and Waiting for approval….
In Ligantic, the request now shows Ready to compare. Select Compare and approve.
Check that the confirmation in the dialog matches the device's exactly, then select It matches — approve.
If it does not match, select Cancel, then Cancel request. Another device may have used the code first.

The device signs in within a few seconds and shows Signed in as device "<name>". Select Continue to open the app. It stays signed in while it is used.

Disable a device on the device itself

Disable a device only if it should stop working.

On the device, open /__auth/device, select Disable this device…, then Yes, disable this device.

The device cannot sign back in until an administrator approves it again.

Let a disabled device back in

On the device, open /__auth/device and select Request to sign back in.
The device shows a new confirmation. If the button is missing, signing back in is not available for your organisation at the moment.
In Ligantic, open the Agent and approve the Re-enable request in the same way as a new pairing.
The request stays open for 10 minutes. If nobody approves it in time, select Request to sign back in again. A disabled device can request at any time until it expires from inactivity.

The device keeps its name and history. Its old sign-in does not come back: it signs in afresh.

Disable or revoke a device from Ligantic

Open the Agent. Under Devices, open the device's actions menu (⋮) and choose:

Disable signs the device out within 30 seconds. It can request to sign back in.
Revoke signs the device out within 30 seconds and permanently removes it. To use the device again, pair it as a new device.

When a device must be paired again

Pair the device again with a new code when:

it was revoked;
it was not used for longer than the organisation's inactivity period (14 days by default) and has expired;
its browser data was cleared, or it is a different browser or profile. The device page says that the browser no longer has its device key;
the Space's app address changed.

On the device page, select Pair again, then follow Pair a device.