- Duale AI
- Documentation
- Identity
- Agent Identity lifecycle
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.
- In the Dashboard, open Agents > Create Agent. Enter the identifier and the display name, then choose Create Agent.
- 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.
- 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 asDUALEAI_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:
- In the Dashboard, open Agents, choose the Agent Identity, then use Tokens > Create Token to issue a replacement.
- Deliver the replacement through your secret-management process.
- Submit a new Task with the replacement and verify the expected result.
- 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.
- 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.
- 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.
- 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. - 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.
- 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.
| 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 |
- 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.
| Level | How the person signs in |
|---|---|
aal1 | With a password, or with a passkey |
aal2 | 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 |
aal3 | With 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:
| Field | What it carries |
|---|---|
action | credential.refuse |
outcome_reason | 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 |
required_action | The requested action, when known |
user_context.identity | The identity that owns the platform token, if any |
changes_after.psk_id | The identifier of the platform token |
- Field
action- What it carries
credential.refuse
- Field
outcome_reason- What it carries
invalid_tokenwhen the platform token cannot be used, for example after its identity was deleted;assurance_below_requirementwhen 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.