Skip to content
Choose one Agent Identity for one operating boundary
Public Preview

Agent Identity credentials and lifecycle

Create an Agent Identity, issue and rotate its API tokens, contain a leaked token, and delete the identity safely.

This guide covers Agent Identity creation, API token rotation, leaked token containment, identity deletion, and permission and assurance level requirements.

  • Agent Identity boundary selection and creation.
  • API token rotation before revocation.
  • Leaked API token containment and identity recovery.
  • Identity deletion and token revocation order.
  • Permission and assurance level requirements per operation.

Summaries were generated by AI.

Create an Agent Identity, issue and rotate its API tokens, contain a leaked token, and delete the identity safely. The Dashboard labels Agent Identities as Agents.

An API token is the credential you issue, store, and rotate, and the only value your secret manager holds. The SDK uses it to obtain short-lived platform tokens for you.

Choose one Agent Identity for one operating boundary

Every API token of an Agent Identity carries that identity’s full access: its permissions, Tools, Library access, and the earlier Tasks that Recall can read. Use a separate Agent Identity, such as one for each end user or trust boundary, when two processes need different access, Tools, or credentials, or must keep their Tasks apart. When a Tenant-wide setting such as the model pool must differ, use another Tenant, as Architecture patterns explains.

You choose the identifier within the identifier rules. It stays fixed when the display name changes. A team prefix such as payments- in payments-invoice-review helps organize identities; a resource pattern on that prefix also covers Agent Identities created later.

Create an Agent Identity without changing its identifier later

Issuing the identity’s token needs agent:create_token and a sign-in with a passkey or security key (aal3). The supplied Editor policy allows creating the identity but not issuing its token, so a person with only that policy asks a member of tenant-admins to issue it.

  1. In the Dashboard, open Agents > Create Agent. Enter the identifier and the display name, then choose Create Agent.
  2. Open the new Agent from the Agents list, then open Tokens > Create Token. Name it and choose its expiry within the API token lifetime. The Dashboard shows the token value only once.
  3. Store the token in your secret manager and give it to the running process as DUALEAI_TOKEN. A process that publishes Tools also needs the identifier as DUALEAI_AGENT_ID; SDK configuration lists every setting.

Rotate an API token before you revoke it

Issuing and revoking a token need a person signed in at aal3, so rotation cannot run unattended. Rotate a token 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 secret-management process.
  3. Submit a new Task with the replacement and verify the expected result.
  4. Wait for the Last Used delay after you deliver the replacement. Then, in the same Tokens tab, check Last Used on the previous token. A time after you delivered the replacement shows that a process still uses the previous token; update that process first.
  5. Choose Revoke on the previous token and confirm its name.

Contain a leaked API token

A revoked token can no longer obtain platform tokens. A platform token already obtained with it keeps working until it expires.

  1. In the Agent’s Tokens tab, revoke the leaked token. If its Last Used time is earlier than the leak, no platform token was obtained with it afterwards, and revocation is enough.
  2. Otherwise, look for Tasks you do not recognize in the Agent’s Tasks tab. To end one, stop it with sdk.stop_task(task_id, reason) from a process that runs as that Agent Identity with another valid token.
  3. Revoke the identity’s other tokens, then delete the identity to end its platform tokens. After deletion, Duale AI stops offering the Tools of a Tool Host that runs as that identity; SDK Tool delivery states when.
  4. Give your application a new Agent Identity instead of recovering the deleted one.

Revoke every token before you delete the identity

A recovered Agent Identity keeps its identifier, so policies written for it apply again. Recovery also brings back every unexpired API token that you did not revoke. In the Dashboard, open the identity’s Tokens tab and revoke each token, then use Advanced > Delete Agent. Deletion ends every token of the identity within the time for access changes to apply; Tasks already accepted run until their deadline.

Stop the processes you control that ran as that identity. After that time, check that an existing client cannot start a new Task.

Allow for authorization propagation separately

A change to a Library Grant, a policy, or a group takes effect everywhere only after the time for access changes to apply. So does deleting an identity or closing a Tenant. After that time, try the action again and check that it works or fails as intended. Review access explains what to test.

Check the permission for each lifecycle operation

Each operation needs the listed action on agent:<agent_id>. Some operations also need a sign-in level.

OperationRequired action
Create an Agent Identityagent:create
Read one Agent Identityagent:read
Update an Agent Identityagent:update
Delete or recover an Agent Identityagent:delete
Issue an Agent Identity API tokenagent:create_token
List an Agent Identity’s API tokensagent:read_token
Revoke an Agent Identity API tokenagent:revoke_token
  • Operation
    Create an Agent Identity
    Required action
    agent:create
  • Operation
    Read one Agent Identity
    Required action
    agent:read
  • Operation
    Update an Agent Identity
    Required action
    agent:update
  • Operation
    Delete or recover an Agent Identity
    Required action
    agent:delete
  • Operation
    Issue an Agent Identity API token
    Required action
    agent:create_token
  • Operation
    List an Agent Identity’s API tokens
    Required action
    agent:read_token
  • Operation
    Revoke an Agent Identity API token
    Required action
    agent:revoke_token

Reach the assurance level an operation requires

Some operations need a recent, stronger sign-in as well as a permission.

LevelHow the person signs in
aal1With a password, or with a passkey
aal2With a password plus a second factor, such as a time-based code or recovery code, or with a passkey unlocked by PIN or biometrics
aal3With a passkey or security key unlocked by PIN or biometrics, when the Dashboard asks for this level
  • Level
    aal1
    How the person signs in
    With a password, or with a passkey
  • Level
    aal2
    How the person signs in
    With a password plus a second factor, such as a time-based code or recovery code, or with a passkey unlocked by PIN or biometrics
  • Level
    aal3
    How the person signs in
    With a passkey or security key unlocked by PIN or biometrics, when the Dashboard asks for this level

A sign-in keeps its level for a limited time. When an operation needs a level that your sign-in no longer meets, the Dashboard asks you to sign in again at that level.

These administration operations require a person signed in at aal3:

  • issuing or revoking an Agent Identity API token;
  • deleting a Tenant, Agent Identity, custom group, policy, Library, or configuration item such as a Model Route or an MCP Connection;
  • removing a member from the Tenant or a group, or removing a policy from a group.

An Agent Identity cannot reach aal3 (Identity limits), so it cannot complete these operations, even when its policies allow the required action.

aal3 also accepts compatible platform and synced passkeys, not only security keys. Duale AI therefore does not claim that aal3 meets NIST AAL3.

Correlate a refused credential in your own SIEM

Your Tenant’s audit history records each refused platform token that Duale AI can link to your Tenant:

FieldWhat it carries
actioncredential.refuse
outcome_reasoninvalid_token when the platform token cannot be used, for example after its identity was deleted; assurance_below_requirement when its sign-in level is too low for the operation
required_actionThe requested action, when known
user_context.identityThe identity that owns the platform token, if any
changes_after.psk_idThe identifier of the platform token
  • Field
    action
    What it carries
    credential.refuse
  • Field
    outcome_reason
    What it carries
    invalid_token when the platform token cannot be used, for example after its identity was deleted; assurance_below_requirement when its sign-in level is too low for the operation
  • Field
    required_action
    What it carries
    The requested action, when known
  • Field
    user_context.identity
    What it carries
    The identity that owns the platform token, if any
  • Field
    changes_after.psk_id
    What it carries
    The identifier of the platform token

Group exported refusals by changes_after.psk_id to find a process that keeps using a refused platform token, for example after you deleted its Agent Identity. Evidence and audit explains how to query and export these records.

Duale AI cannot link a request made with a revoked API token to a Tenant, so keep your own evidence of that request. What the audit log does not record states what to keep.