Agents
An Agent is a non-human identity controlled by an organisation. It has no password and does not sign in to Studio. It acts through API keys, with the public API, the SDK or the CLI, and through paired devices, in a Space's App. This page describes Agent properties, limits, organisation membership, Space access, API keys, removal, permissions and the matching API and CLI operations. For a guided walkthrough, see Your First Agent and Paired Device.
Where Agents Are Managed
In Studio, open Organisations → your organisation → Agents. The tab lists each Agent's Name, with a Remove action, and Create an Agent.
Selecting an Agent opens Agent Details with these sections:
Section | Contents |
|---|---|
Details | ID, Name and Email. |
API Keys | The Agent's API keys and Create API Key. See API Keys. |
Spaces | The Spaces the Agent has joined, its role in each, and Join Agent to Space. See Spaces. |
Devices | Paired devices and pairing requests. Shown to holders of |
Agent Properties
Property | Description |
|---|---|
ID | Assigned when the Agent is created. Used in API paths and CLI arguments as |
Name | Required in Studio. Through the API it is optional and defaults to the Agent's ID. It cannot be changed after creation. |
Generated from the name and the organisation ID. It identifies the Agent, for example as the account shown by | |
Join Organisation | Set at creation only. Off by default. See Organisation Membership. |
Agent Limit
The organisation's plan sets how many Agents it can have. Depending on the plan, the limit is fixed or a number of Agents per seat. Create Agent shows the usage as Agents: <used> / <limit>.
Situation | What you see |
|---|---|
The plan does not include Agents |
|
The limit is reached |
|
Removed Agents do not count towards the limit. Devices do not count towards it either; they have their own per-Agent limit, listed in Devices — Limits.
Organisation Membership
With Join Organisation on, the Agent also becomes a member of the organisation:
- It is listed on the Members tab with the type Member.
- It uses a seat. See Organisations — Seats.
- Its API keys carry the member permissions: listing, creating, joining and transferring Spaces in the organisation. See Organisations — Membership Types.
With Join Organisation off, the Agent is not a member. It has no organisation permissions and reaches only the Spaces it is joined to.
Spaces
An Agent reaches a Space only after it is joined to it. An Agent can join only Spaces owned by its organisation.
Join Agent to Space opens Join Space as Agent, which lists the organisation's Spaces with the Agent's role in each (Space User Role):
- Join as Agent adds the Agent to the Space as User - built-in.
- Leave as Agent takes the Agent out of the Space.
On the Agent's Spaces table, a Space admin can change the Agent's role in that Space, or select Remove to take it out. These controls appear only for Spaces where you are an admin. For what each role allows, see Space Roles and Permissions.
When the Agent leaves or is removed from a Space, its API keys and its paired devices lose access to that Space. The Agent can be joined again later.
API Keys
An Agent API key authenticates requests as the Agent. A request made with it can do what the Agent's role allows in each Space the Agent has joined, plus its organisation permissions if it is a member.
Create API Key opens Create Agent API Key:
Field | Required | Description |
|---|---|---|
Name | No | A label for your reference. |
Expires At | No | Date and time after which the key stops working. Must be in the future. Without it, the key does not expire. |
After Create API Key, the API Key Created page shows the full key once, with a copy button. It cannot be shown again. The API Keys table lists each key by a masked form of its ID (lak_<first 10 characters>***_eak), with Name, Expires and Remove.
Remove revokes the key immediately. Systems using it can no longer access the API. Removal cannot be undone.
Use an Agent API key in the same way as any other API key, for example with ligantic auth login. See CLI Command Reference — auth.
Removing an Agent
Remove on the Agents tab, then Remove Agent, permanently removes the Agent:
- All of its API keys are revoked.
- It loses access to every Space and resource.
- Its paired devices can no longer sign in.
Removing the organisation removes all of its Agents.
Permissions
Organisation permission | Allows |
|---|---|
| Viewing the Agents tab and an Agent's details |
| Creating Agents |
| Removing Agents |
| Viewing the Spaces an Agent has joined |
| Joining an Agent to a Space. Also needs |
| Viewing an Agent's API keys |
| Creating Agent API keys |
| Removing Agent API keys |
Organisation owners have all of them. Members have none. Changing an Agent's role in a Space, or removing it from a Space, needs the Space admin role in that Space instead. For device permissions, see Devices — Permissions.
API and CLI
Operation | REST | CLI |
|---|---|---|
List Agents |
|
|
Create an Agent |
|
|
Get an Agent |
|
|
Remove an Agent |
|
|
List the Agent's Spaces |
|
|
List the organisation's Spaces with the Agent's role |
|
|
Join the Agent to a Space |
|
|
List API keys |
|
|
Create an API key |
|
|
Remove an API key |
|
|
Manage devices |
|
|
… is /api/v1/organisations/{organisationId}/agents/{agentId}. Except for the device operations, the generated CLI help and the API specification name the organisation ID in these paths controllingOrganisationId. Create takes name and joinOrganisationAsMember. Create API key takes name and expiresAt, an ISO 8601 date and time with an offset, and returns the key once as apiKeyText. ligantic organisations spaces join uses the current Space, or --space <id>. Remove operations need --yes in the CLI.