Agent identity

An agent is a first-class identity, alongside people and service accounts. It acts under its own name, holds its own permissions, and belongs to exactly one workspace. This page explains how a worker proves which agent it is, why the credential rather than the name is what is trusted, and how you rotate or revoke that credential.

​

An agent as a principal

Every run, log line, and piece of evidence an agent produces is attributed to the agent, not to whoever triggered it. That is what makes an agent’s history reviewable: you can ask what this agent has done, and get an answer that is not tangled up with the people who invoked it. When an agent registers it is granted the built-in Agent role — a least-privilege default that deliberately excludes the credential-minting actions an autonomous worker must never hold. That is the role every agent holds unless you narrow it. You manage an agent’s roles from Settings → Agents, with the same model used for members; see Roles & permissions.

​

Name and identity are different things

An agent has a friendly name — its slug, something like triage — which is what you see in the console and in URLs. That name only has to be unique inside your workspace, so two workspaces can each run a triage agent with entirely separate identities and no way to detect one another. Underneath, each agent has a stable opaque identity that the platform uses to attribute work and enforce isolation.

​

How a worker authenticates

An agent runs as a worker — one process hosting one agent. The worker authenticates with a worker token issued for that specific agent, and sends its friendly name alongside it. You do not assemble any of this by hand. The SDK attaches the credential to registration, heartbeat, run-claim, and evidence requests for you.

​

Configuring a worker

The SDK reads the worker’s identity and its target control plane from the environment:

​

Managing a worker token

A token is minted when the agent is created and delivered to the worker as a secret — an environment variable or a mounted secret. Keep it out of source control. Every self-deployed worker authenticates with a revocable token bound to its agent, managed from Settings → Agents → Worker tokens. Tokens for agents that have not registered yet are listed too, so a token can be prepared before its worker comes online. The value is shown only once, when it is issued or rotated: Token creation and revocation are both recorded in the audit log.

​

Next steps