--- title: "Agent Identity credentials and lifecycle" description: "Create, rotate, and revoke Agent Identity API tokens, and manage identity deletion and assurance requirements in Duale AI." lang: en status: public-preview lastUpdated: 2026-10-18 url: https://dev.duale.ai/en/docs/identity/credentials-and-lifecycle --- ## AI-generated summary This guide covers Agent Identity boundaries, credential types, token rotation and revocation, identity deletion and recovery, and assurance level requirements. - Agent Identity boundary and identifier selection. - Credential types and their exchange roles. - Token rotation and revocation procedures. - Identity deletion, recovery, and propagation window. - Assurance levels and per-operation permission checks. Summaries were generated by AI. --- 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](https://dev.duale.ai/en/docs/identity.md) 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](https://dev.duale.ai/en/docs/security/end-to-end-encryption.md) 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](https://dev.duale.ai/en/docs/identity/limits.md) 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. | Credential | Who holds it | What it does | | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | | A signed-in Human Identity's credential | A Tenant member | Obtains a platform token for that Human Identity | | An Agent Identity API token | Your running process | Identifies that process to Duale AI in exchange for a platform token | | A platform token | A Human Identity's client or an Agent Identity's process | Authenticates and encrypts protected calls, including permitted administration | 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//` 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](https://dev.duale.ai/en/docs/identity/policies.md) explains how those permissions combine, and [default policies](https://dev.duale.ai/en/docs/identity/default-policies.md) owns the baseline grants. [Library access and isolation](https://dev.duale.ai/en/docs/libraries/access.md#who-can-grant-what) owns Library creation and Grant rules. ## Create an Agent Identity without changing its identifier later You need `agent:create` on `agent:` 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](https://dev.duale.ai/en/docs/scope-and-limits.md#runtime-ceilings-and-deadlines) 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](https://dev.duale.ai/en/docs/identity/credentials-and-lifecycle.md#allow-for-authorization-propagation-separately). Deletion does not cancel work the Platform already accepted. Deletion requires `agent:delete` on `agent:` 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](https://dev.duale.ai/en/docs/identity/credentials-and-lifecycle.md#allow-for-authorization-propagation-separately) 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](https://dev.duale.ai/en/docs/sdk/tools.md) 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](https://dev.duale.ai/en/docs/tools/mcp-connections.md) 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. | Level | How the Human Identity authenticated | | ------ | ------------------------------------------------------------------------------------------------------------------------------- | | `aal1` | Signed in with a password, or with an accepted passkey | | `aal2` | Used a passkey with user verification, or a password plus a configured second factor such as a time-based code or recovery code | | `aal3` | Used public-key multi-factor authentication with user verification, through a compatible passkey or security key | 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](https://dev.duale.ai/en/docs/libraries/access.md#what-each-action-allows) 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: | Field | What it carries | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | `credential.refuse` | | `psk_id` | The key identifier presented on the refused request | | `failure_reason` | `invalid_token` when the credential cannot be used for the requested Tenant, `assurance_below_requirement` when its certified level is below the route's requirement | | `requested_action` | The requested action, when the route had selected one | | `resolved_identity` | The subject, when the credential still resolved to one | 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](https://dev.duale.ai/en/docs/security/evidence-and-audit.md) 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:`. The operation can also have a separate authentication requirement, which an access policy does not replace. | Operation | Required action | | ----------------------------------- | -------------------- | | Create an Agent Identity | `agent:create` | | Read one Agent Identity | `agent:read` | | Update an Agent Identity | `agent:update` | | Delete or recover an Agent Identity | `agent:delete` | | Issue an Agent Identity API token | `agent:create_token` | | List an Agent Identity's API tokens | `agent:read_token` | | Revoke an Agent Identity API token | `agent:revoke_token` | | Obtain a platform token | `agent:mint_token` | `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](https://dev.duale.ai/en/docs/identity/default-policies.md) before you assign a tier. For narrower access, an authorized person or Agent Identity can author a scoped [Tenant policy](https://dev.duale.ai/en/docs/identity/policies.md#author-a-narrow-tenant-policy) and bind it to a suitable subject; verify one intended operation and one that must remain refused. ## Related content - [Identity and access for AI agents on Zero Trust](https://dev.duale.ai/en/product/identity-and-access.md) - [Security controls for your agent platform](https://dev.duale.ai/en/product/security.md) - [Legal: every point quoted, ready for decision](https://dev.duale.ai/en/use-cases/legal.md) - [Terms of Use: Platform access and responsibilities](https://dev.duale.ai/en/legal/cgu.md) - [Tenant policies: binding, permissions, and authoring](https://dev.duale.ai/en/docs/identity/policies.md) - [Data protection: encryption, deletion, and transit](https://dev.duale.ai/en/docs/security/data-protection.md) --- ## Sitemap See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.