Agent Identity credentials and 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.

An API token is the credential you issue, store, and rotate. Your process presents it to Duale AI when obtaining or renewing a short-lived platform token. Platform services use the platform token to authenticate and encrypt protected calls. The SDK performs the exchange and renews the platform token for you, so the API token stays the only value your secret manager holds. End-to-end encryption explains the protected exchange.

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 by default; a policy author with authority to confer the permission can grant agent:read_task on that Agent Identity’s Tasks. Identity limits explains where the Agent Identity boundary ends.

Use the credential required for each step

Sign-in credentials and Agent Identity API tokens obtain platform tokens. Protected administration and runtime calls then use those platform tokens, with the permissions and assurance level of the identity they represent.

The supplied Agent default policy gives every Agent Identity the same baseline: obtain a platform token, submit and continue Tasks, register a Tool Host and keep it alive, start document uploads, and create, read, and write Libraries under its own agent/<agent_id>/ path. The baseline reaches only this Agent Identity’s own Tenant. Direct policy bindings and group membership widen that baseline to whatever an administrator confers, up to what that administrator holds; review both. Tenant access policies explains how those permissions combine, and default policies owns the baseline grants. Library access and isolation owns Library creation and Grant rules.

Create an Agent Identity without changing its identifier later

You need 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. Start a fresh client with the revoked token and confirm it is refused when it asks for a platform token.

Revoking one token leaves the identity’s other tokens live, and it reaches the exchange rather than the calls. A process that already holds a platform token keeps working on it: a platform token issued to an Agent Identity lasts eight hours, and revoking the API token behind it stops the renewal rather than the token in hand. Stop processes you control when they must cease sending requests. Revocation alone does not end access from other copies of a live platform token.

Revocation also 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.

Step 5 asks for a fresh client because that is the request revocation reaches. A client that is already running holds a live platform token and is answering from it.

Revoke every token before you delete the identity

Deleting an Agent Identity stops it obtaining a platform token. Fresh authorization checks also reject the deleted identity, even when its platform token has not expired. Cached authorization results can remain usable during the authorization propagation window. Deletion does not cancel work the Platform already accepted.

Deletion requires agent:delete on agent:<agent_id> and aal3; recovery requires the same permission and aal2. Recovery makes every unexpired, unrevoked API token work again, and policies written for the original identifier still name it. Recovery can also make an unexpired platform token usable again, even if you revoked the API token that obtained it; current permissions still apply.

In the Dashboard, open the identity’s Tokens tab and revoke each token, then use Advanced > Delete Agent. Stop the processes you control that were running as that identity. Verify with a fresh client that the old API tokens are refused at the exchange. After the propagation window, confirm that an existing client cannot start a new Task. If you later recover the identity through the Profile API, issue a new token instead of restoring an old credential to service.

Closing the Tenant makes all its platform tokens unusable once cached credential and permission results expire. Allow for the authorization propagation window before checking that access has ended.

Manage SDK Tool Host availability and MCP Connection credentials

An SDK Tool Host publishes its Tools with its own heartbeat. It leaves routing four minutes after its last accepted heartbeat; losing that heartbeat does not revoke its Agent Identity API token. Revoking the API token prevents platform-token renewal, but a process can continue authenticated heartbeats while its existing platform token remains usable. The four-minute routing window starts after the last accepted heartbeat, not when you revoke the API token. 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.

Reach the assurance level an operation requires

Permission answers what you hold. Assurance answers how you proved who you are, and some operations require both. Duale AI certifies the level once, when it issues the platform token, and every service compares against that one answer.

Product level aal3 accepts compatible platform and synced passkeys as well as security keys. Two exceptions prevent a NIST AAL3 compliance claim: authentication keys need not be non-exportable and hardware-protected, and authenticators need not have FIPS 140 validation. A password plus a time-based code or recovery code does not establish aal3.

A Human Identity’s qualifying authentication lasts at most 30 days at aal1, 7 days at aal2, or 12 hours at aal3, measured from the original qualifying sign-in. The inactivity limits are also 7 days at aal2 and 12 hours at aal3; aal1 has no separate inactivity limit. Platform tokens for Human Identities last at most 10 minutes and never pass the selected authentication deadline. The Dashboard renews them in the background while that authentication remains valid. Renewing a platform token or an identity-provider token does not restart these authentication windows.

An Agent Identity is certified at aal2 whenever it obtains a platform token, and stays there. Through the Profile API, issuing or revoking an Agent Identity API token, removing your own authentication methods, and ending your own sessions require a Human Identity at aal3. Assurance is the one axis a policy cannot widen—an allow says you hold the action, and the level is a separate question the same decision answers.

Other IAM operations also require aal3: deleting a Tenant, Agent Identity, custom group, or policy; removing a Tenant member or a group member, including a human-tier membership; and removing a policy binding from a Human Identity, Agent Identity, or group. An Agent Identity cannot perform these cleanup steps even when its policies grant the required action. Have an authorized Human Identity complete them with valid aal3 authentication. Features can impose their own requirements; see Library deletion before automating Library cleanup.

When qualifying authentication is missing or expired, the Platform refuses and names the authentication requirement. The Dashboard turns that into a sign-in prompt; a client of your own reads the requirement off the refusal and re-authenticates. Reaching that level does not grant the permission: the operation still checks access after the assurance requirement is met.

Correlate a refused credential in your own SIEM

Credential refusals recorded in your Tenant’s audit history include the public key identifier the caller presented. Use that identifier to correlate repeated presentations in your own SIEM:

The identifier is stable across presentations of one credential. Export the audit history to correlate the recorded refusals with your own records. Evidence and audit owns the query and export interface.

This history has a coverage gap. A request rejected before the Platform can resolve its encryption key and identify the Tenant does not appear in customer audit history. An expired or deleted platform token can fail at that boundary. The absence of a Tenant event therefore does not prove that nobody presented the credential again. Keep the failure information your client receives when you need evidence of those attempts.

An invalid_token refusal leaves resolved_identity empty: no actor is attributed to that request. An assurance_below_requirement refusal names the resolved subject, but says nothing about whether that subject has the requested permission. The permission check follows successful authentication.

Recording the identifier discloses nothing a reader of the traffic did not already have: it is random, it travels in the clear on every request, and once the record is gone it opens nothing.

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.

agent:mint_token is checked against the Agent Identity requesting its own platform token. The supplied Agent default grants it to every Agent Identity. A narrower policy cannot remove that supplied permission; use the token-revocation or identity-deletion steps above to stop new platform tokens.

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 or Agent Identity can author a scoped Tenant policy and bind it to a suitable subject; verify one intended operation and one that must remain refused.