Manage Agent Identity credentials and token lifecycle

The Dashboard labels Agent Identities as Agents. Open an Agent’s Tokens tab to issue or revoke its API tokens. Choose the identity’s boundary and identifier before setup, then follow the sequence below so recovery cannot reactivate an old token. Identity explains which principal the token represents.

Choose one Agent Identity for one operating boundary

Use a separate Agent Identity when credentials, authorization, available Tools, Task attribution, event ownership, or review responsibility must differ. A team or project name alone does not require another identity when those boundaries stay the same. Your organization chooses an identifier of 3 to 50 characters: start with a letter, then use letters, digits, hyphens, or underscores. The identifier is unique within one Tenant and does not change when the display name changes. A team prefix such as payments-invoice-review can help organize identities, but the prefix is a naming convention, not a Tenant or access boundary.

The Agent Identity carries its own API tokens, available Tool references, Task attribution, Task events, and root-Task history view. It does not carry a separate model pool, provider credential, cost view, or Agent behavior version. A Task attributed to another Agent Identity does not expose its events to this one. Identity limits explains where the Agent Identity boundary ends.

Use separate administration and runtime credentials

The credential used to administer an Agent Identity and the API token used by a process acting as that identity are not the same credential.

By default, an Agent Identity API token submits Task requests and opens a document upload. Its library:upload permission alone does not let it create a Library. It does not author a policy, read your model-provider configuration, or change your model pool. It acts only inside its own Tenant. Direct policy bindings and group membership can widen its access within the Agent Identity ceiling; review both. Tenant access policies explains how those permissions combine, and default policies owns the baseline grants. Library access and isolation owns creation and creator Grant rules.

Create an Agent Identity without changing its identifier later

A person needs agent:create on agent:<agent_id> to create the identity and a separate agent:create_token permission to issue its token. The supplied Editor policy allows creation but not token issuance; a person with only that policy must ask a token issuer to finish setup.

1. In the Dashboard, open Agents > Create Agent. Enter the Agent Identity public identifier and display name, then choose Create Agent. Renaming later changes the display name, not the identifier that policies and records use.
2. On the new Agent settings page, open Tokens > Create Token. Name it and choose its expiry. The Platform shows the token value only once.
3. Copy the token to your approved secret manager. Give the running process that token and the Agent Identity public identifier (agent_id).

Rotate an API token before you revoke it

An API token lasts from 1 to 365 days and defaults to 90 days. Rotate it in this order:

1. In the Dashboard, open Agents, choose the Agent Identity, then use Tokens > Create Token to issue a replacement.
2. Deliver the replacement through your approved secret-management process.
3. Submit a new Task with the replacement and verify the expected result.
4. In the same Tokens tab, choose Revoke on the previous token and confirm its name.
5. Verify that the revoked token is refused on both a new Task request and any Library operation it can reach.

Revoking one token leaves the identity’s other tokens live. It stops new Task requests, but it does not cancel work the Platform already accepted. That work remains governed by its accepted deadline and other terminal conditions. Scope and limits owns the deadline contract. Revocation takes effect on the next Task request, but a revoked token can still be accepted on Library calls for up to 30 seconds. Wait through that Library window before you verify refusal.

Revoke every token before you delete the identity

Delete is not revocation. Deleting an Agent Identity stops it and its tokens from working, but a person authorized for agent:delete on agent:<agent_id> can recover it. Recovery makes every unexpired, unrevoked token work again, and policies written for the original identifier still name it.

In the Dashboard, open the identity’s Tokens tab and revoke each token. Wait through the 30-second Library window and verify that the old tokens are refused. Then use Advanced > Delete Agent. If you later recover the identity through the Profile API, issue a new token instead of restoring an old credential to service.

Keep Tool credentials separate from Agent Identity tokens

An SDK Tool Host publishes its Tools with its own heartbeat. It leaves routing four minutes after its last heartbeat; losing that heartbeat does not revoke its Agent Identity token. Conversely, revoking one token stops new authenticated heartbeats from the process using it, but does not immediately remove its Tool Host from routing. SDK Tool delivery owns the Host lifecycle.

A remote MCP server uses the credentials of its named MCP Connection, not the Agent Identity API token. Disabling the Connection stops new remote calls without revoking Agent Identity tokens. MCP Connections owns connection setup, assignment, and retirement.

Allow for authorization propagation separately

A Library Grant, Tenant policy, or group change can take up to one minute to take effect. After that window, repeat the affected operation and confirm the intended allow or refusal. For an additive policy change, also check one neighboring operation that must remain refused.

Check the permission for each lifecycle operation

Each operation checks the listed action against agent:<agent_id>. The operation can also have a separate authentication requirement, which an access policy does not replace.

These actions are Tenant-scoped unless the assigned policy narrows their resource pattern. Review the exact supplied policy grants before you assign a tier. For narrower access, an authorized person can author a scoped Tenant policy and bind it to a suitable subject; verify one intended operation and one that must remain refused.