Agents

An agent acts for you. Use one for your own tooling: the command line, a script you run, or an AI agent you hand access to. For an integration that a team owns, use an app instead: an agent ends when you leave the organization.

• It can do what you can, within its scopes. An agent has your teams and grants, as a member, at the time of each request. It never has your owner or admin role, so organization administration stays in the browser. Its scopes narrow it further: an agent with alerts:read can only read alerts. If you lose access to something, your agents lose it too.
• It is recorded as itself. The audit log names the agent and the person it acts for, so what an agent did is told apart from what you did.
• It holds clients. A client is a client id and a secret that the agent signs in with. See API authentication. Each client expires within 90 days, and an agent holds at most 2, so you can create the new one before you delete the old.

LimitsCopy Anchor Link

• You can have up to 10 agents.
• An agent can never break glass, change a password or multi-factor setting, or create, change or list agents and clients.
• An agent stops working at once when you delete it, or when you are removed from the organization or deactivated. A client also stops at its expiry.

Create an agentCopy Anchor Link

Creating an agent, changing its scopes and creating a client all need a fresh identity check: a passkey or security key, or a password sign-in with an authenticator code, made in the last 10 minutes. Deleting needs none.

Over the API, while signed in:

1. POST /users/me/agents with a name and its scopes. Each scope must be one you hold yourself as a member.
2. POST /users/me/agents/{id}/clients with a name and an expires_at. The answer holds the client id and its secret. The secret is shown only once.

GET /users/me/agents lists your agents and their clients. DELETE /users/me/agents/{id} deletes an agent and its clients.

Organization owners and admins can list and delete anyone's agents: GET /users/{id}/agents and DELETE /users/{id}/agents/{agent_id}.