Your First Agent and Paired Device

In this tutorial we will create an organisation Agent, give it access to one Space, sign in to the CLI with its API key, and pair a browser so that it opens the Space's App as the Agent. At the end, the CLI and the browser both act as the Agent, and only in that Space.

Prerequisites

An organisation where you are an owner, on a plan that includes Agents. See Organisations.
A Space owned by that organisation, which you have joined from the organisation's Spaces tab. Joining makes you a Space admin, so you can change the Agent's role later.
The CLI, installed with npm install -g @ligantic/cli. See CLI Command Reference.
For the last step: device pairing enabled for your organisation, and a second browser, such as a tablet running an up-to-date Chrome. If the Agent page has no Devices section, pairing is not enabled; you can still complete steps 1 to 4.

Step 1: Create the Agent

In Studio, open the user menu and select Organisations, then your organisation.
Open the Agents tab and click Create an Agent.
Enter Front Desk in Name. Leave Join Organisation off, so the Agent gets access only to the Spaces we join it to.
Click Create Agent.

Studio opens Agent Details. Notice the ID, the Name Front Desk, and an Email that starts with front-desk@. The API Keys and Spaces sections are empty.

Step 2: Join the Agent to Your Space

Under Spaces, click Join Agent to Space.
Join Space as Agent lists the organisation's Spaces. Next to your Space, click Join as Agent.
A Joined space message appears, and the button changes to Leave as Agent. The Space User Role column now shows User.
Click Back.

The Agent's Spaces table lists your Space with the role User - built-in. Because you are an admin of that Space, the role is a select you could change. Leave it as it is for this tutorial.

Step 3: Create an API Key

Under API Keys, click Create API Key.
Enter cli in Name. Leave Expires At empty.
Click Create API Key.

The API Key Created page shows the key. Click the copy button next to it and keep the key somewhere safe for the next step. This is the only time the full key is shown.

Click Done. The API Keys table now lists the key by a masked ID that starts with lak_.

Step 4: Use the Key with the CLI

In a terminal, note which profile you are using now. ligantic auth list marks it with *:
```
ligantic auth list
```
Sign in with the Agent's key under a separate profile, so your own credentials are kept:
```
ligantic auth login --profile front-desk
```
Paste the key at the hidden prompt. If the CLI offers to open the Space picker, select your Space.

Check who you are signed in as:

ligantic auth whoami

The output should look something like this:

id:    <agentId>
account: credentials (front-desk@<organisationId>.<domain>)
space: <spaceId> (<spaceTitle>)

Notice that id is the Agent's ID from Step 1.

List the Spaces the key can reach:
```
ligantic spaces list
```
Only the Space from Step 2 is listed. Your other Spaces are not, because the Agent has not joined them.
Switch the CLI back to the profile you noted in step 1, for example default:
```
ligantic auth use default
```

Step 5: Pair a Device

Now we give the same Agent a browser. Have the device in front of you.

In Studio, on the Agent's page, find the Devices section and select Pair a device. A dialog shows an 8-digit pairing code, such as 4829-1305.
On the device, open your 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 device shows a 6-digit confirmation, such as 482 913, and Waiting for approval….
In Studio, the request shows Ready to compare. Select Compare and approve.
Check that the confirmation matches the one on the device, then select It matches — approve.

Within a few seconds the device shows Signed in as device "<name>". Select Continue. The device opens the Space's App as Front Desk, with the Agent's User - built-in role, and nobody entered a password on it. In Studio, the device is listed under Devices with the state Enabled.

What You Built

You created an Agent that can reach exactly one Space. You gave it an API key and used that key with the CLI, and you paired a browser that signs in to the Space's App as the same Agent. Removing the Agent from the Space would cut off both the key and the device; removing the Agent itself would revoke them for good.