Agent identity

An agent identity lets an automated agent act under its own name instead of borrowing a person’s credentials. Each agent has one human owner, a policy that caps what it can do, and credentials that can be revoked without touching anyone else’s access. Tool calls, sessions, and changes the agent makes are attributed to the agent, so audit logs and risk findings show what the agent did rather than blaming the person who set it up. For the underlying model, see What agent identity is.

Agents appear alongside people on the Identity > Identities page, filtered with Agents. Create one with New agent identity.

Access requirements

Any organization member can create an agent and manage the agents they own. Managing someone else’s agent requires the agent:read, agent:write, agent:authorize, or agent:transfer scope from Roles and Permissions. The Admin role holds all four.

How authorization is evaluated

An agent request succeeds only when three policies all allow it:

• The credential policy. An API key or MCP session carries a fixed maximum policy, set when a person issued or approved it. It is never widened afterward.
• The agent policy. The permissions configured on the agent, plus the permissions of any roles the agent is assigned to. This is the most the agent can ever be delegated.
• The owner’s policy. The owner’s current permissions. An agent can never do more than its owner.

The agent and owner policies are read live on every request, so removing a permission from either takes effect immediately. The request is also refused when the credential is revoked or expired, when the agent is suspended, revoked, or deleted, or when the owner has left the organization.

Sharing an agent

People other than the owner can use an agent, for example by issuing their own API key for it or by messaging an assistant that runs as the agent. Using an agent never gives a person more access than they already have. Each request is limited to what the agent, its owner, and the person using it are all allowed.

For example, if an owner with project:write gives that permission to an agent, a teammate without project:write still cannot write projects through the agent.

An API key keeps the limits it was issued with. After removing a permission from someone, rotate the agent API keys they issued.

An agent with no permissions can hold API keys, but those keys authorize nothing.

Create and authorize an agent

Create an agent with the New agent identity wizard on the Identities page. The wizard sets the agent’s servers and tools, gives it an API key or workload identity, and confirms its first call. The person creating the agent becomes its owner. See Authorizing agents for each step.

Set the agent policy

The Permissions section on an agent holds its policy. Only scopes that are safe for a nonhuman caller are offered. The MCP access tab holds mcp:connect. The Platform access tab holds every other scope: MCP server administration (mcp:read, mcp:write, which also connect to the servers they cover with every tool), project build and deploy (project:read, project:write), environments (environment:read, environment:write), skills (skill:read, skill:write), assistants (assistant:read, assistant:write), inference:execute for running inference in chosen projects, risk_policy:evaluate, org:hooks_ingest for hook events, and org:device_agent_sync for the device agent. Each permission can apply to every resource of its kind or be narrowed to chosen resources, down to individual MCP servers and specific tools. An agent can only be given permissions that both the person editing it and its owner hold. Select Save permissions to apply the change.

Agents can also be given access in the places access is managed for people:

• Assign an agent to a role in the role editor on Roles and Permissions, under Assign Agents. A role cannot give an agent a scope that is not safe for agents; those rows are marked “Not available to agents”.
• Grant an agent access to an MCP server from that server’s access settings by choosing Agent under Grant access.

Agent role assignments exist only in the platform and are never synced to the identity provider.

Transfer or reassign an agent

Transferring an agent moves it to a new owner, which changes whose policy bounds it. If the owner leaves the organization or is deactivated, the agent is blocked until it is reassigned to a new owner. Transfer and reassignment require ownership or the agent:transfer scope and are available through the API.

Suspend, revoke, or delete an agent

Three actions on the agent page end or pause its access:

Action	Effect	Reversible
Suspend	Blocks the agent’s credentials without changing its owner or policy. Resume restores them.	Yes
Revoke agent	Permanently prevents the agent from becoming active again.	No
Delete agent	Removes the agent and frees its name for reuse. Its audit history is kept.	No

Each change applies to new requests immediately. Revoke and delete ask for confirmation.

Where agents appear

Agents are listed on the Identities roster with the Agent kind, and each agent’s identity page shows its status, owner, configured permissions, recent changes, authorization checks, and current sessions. Every change to an agent is recorded in Audit Logs with its before and after state.