--- title: "Manage Agent Identity credentials and token lifecycle" description: "Agent Identity API tokens follow a lifecycle of creation, rotation, and revocation with a 30-second Library acceptance window after revocation." lang: en status: public-preview lastUpdated: 2026-09-26 url: https://duale.ai/en/docs/identity/credentials-and-lifecycle --- ## AI-generated summary Manage Agent Identity credentials, token rotation, revocation, and deletion with separate administration and runtime credentials. - Token expiry ranges from 1 to 365 days, defaulting to 90 days. - Revocation stops new Task requests; Library calls may accept revoked tokens for 30 seconds. - Deleting an identity does not revoke tokens; recovery reactivates all unexpired, unrevoked tokens. - Rotate tokens by issuing a replacement, verifying it, then revoking the previous token. - Authorization propagation for policy or group changes can take up to one minute. 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://duale.ai/en/docs/identity.md) 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](https://duale.ai/en/docs/identity/limits.md) 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. | Credential | Who holds it | What it does | | ------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ | | A signed-in person's credential | A Tenant member with the required permission | Authenticates Agent Identity and token-management requests | | An Agent Identity API token | Your running process | Submits Task requests, serves SDK Tools, and uses Libraries it can reach | 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](https://duale.ai/en/docs/identity/policies.md) explains how those permissions combine, and [default policies](https://duale.ai/en/docs/identity/default-policies.md) owns the baseline grants. [Library access and isolation](https://duale.ai/en/docs/libraries/access.md#who-can-grant-what) owns creation and creator Grant rules. ## Create an Agent Identity without changing its identifier later A person needs `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. 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](https://duale.ai/en/docs/scope-and-limits.md#runtime-ceilings-and-deadlines) 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:` 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](https://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://duale.ai/en/docs/tools/mcp-connections.md) 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:`. 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` | These actions are Tenant-scoped unless the assigned policy narrows their resource pattern. Review the exact [supplied policy grants](https://duale.ai/en/docs/identity/default-policies.md) before you assign a tier. For narrower access, an authorized person can author a scoped [Tenant policy](https://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 - [Document encryption, integrity, and deletion lifecycle](https://duale.ai/en/docs/libraries/security.md) - [Security decision points for Task execution](https://duale.ai/en/docs/security.md) - [Agent harness execution model and Task lifecycle](https://duale.ai/en/docs/agent-harness.md) - [Library access: grants, actions, and refusal precedence](https://duale.ai/en/docs/libraries/access.md) - [Documentation for building and operating agent integrations](https://duale.ai/en/docs.md) - [Best practices for managing Library documents](https://duale.ai/en/docs/libraries/best-practices.md) --- ## Sitemap See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.