Token Exchange for AI Agents¶

This guide walks you through how an AI agent can act on behalf of a user by exchanging a token that the user already holds. The flow uses the token exchange grant, as defined in the OAuth 2.0 Token Exchange specification (RFC 8693).

The issued token identifies the user in the sub claim and records the agent as the acting party in the act claim. A resource server can then see both identities in a single token.

Agent friendly delegation mechanism

This flow does not use redirects and needs no new user interaction.
It is suited to bringing an agent into work the user has already authorized.
The agent reuses the token it already obtained through its own authentication flow.

How the flow works¶

As shown in the above sequence diagram, the flow proceeds as follows.

Agent Authentication The agent authenticates with its Agent ID and Agent Secret and obtains its own access token, as described in AI agent acting on its own. This token becomes the actor_token.
Task Delegation The user, or an agent earlier in the chain, delegates a task to the agent and provides the subject token. The subject token identifies the user on whose behalf the agent acts. WSO2 Identity Server accepts a token issued by itself or by a trusted token issuer, as described in Token exchange flows.
Token Exchange Request The agent sends both tokens to the token endpoint using the token exchange grant.
Validation WSO2 Identity Server validates both tokens, resolves the agent from the sub claim of the actor token, and verifies that the agent is a registered and active identity in the organization.
Delegated Token Issuance WSO2 Identity Server issues an access token that carries the user in sub and the agent in act.sub.
Authorized Request The agent calls the protected resource with the delegated token. The resource server can authorize the request against the user's identity while attributing the action to the agent.

Requesting a delegated token¶

Before you begin

Enable the token exchange grant for the application that requests the token, as described in Enable token exchange in your app.
Configure the agent's application to issue JWT access tokens. WSO2 Identity Server rejects opaque actor tokens.

Send both tokens to the token endpoint.

Request Format

curl --location 'https://localhost:9443/t/{root_organization_handle}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64 Encoded (clientId:clientSecret)>' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token={user_token}' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
--data-urlencode 'actor_token={agent_token}' \
--data-urlencode 'actor_token_type=urn:ietf:params:oauth:token-type:jwt' \
--data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'scope={requested_scopes}'

The request contains the following delegation parameters:

Parameter	Description
`subject_token`	A JWT token that identifies the user on whose behalf the agent acts.
`actor_token`	A JWT token issued by WSO2 Identity Server for the agent.
`actor_token_type`	Should be `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:jwt`.

The delegated token¶

The decoded token identifies the user in sub and the agent in act.sub.

{
  "sub": "<user_identifier>",
  "act": {
    "sub": "<agent_identifier>"
  },
  ...
}

A resource server can use the act claim to record which agent acted for the user, or to apply policies that depend on the acting agent. This gives you an audit trail that attributes the action to the agent independently of the user, as described in Comprehensive auditing and explainability.

Chaining delegation across agents¶

When an agent hands a task to another agent, the second agent exchanges the delegated token again with its own actor token. The new agent becomes the current acting party and the existing act claim nests under it, so the token carries the full chain.

{
  "sub": "<user_identifier>",
  "act": {
    "sub": "<second_agent_identifier>",
    "act": {
      "sub": "<first_agent_identifier>"
    }
  },
  ...
}

The most recent agent appears at the top level of the chain. When the request presents no actor token, WSO2 Identity Server carries the existing chain forward unchanged. An agent that re-exchanges a token it received can't alter the chain behind it.

To learn more about the delegation model and the act claim, see Delegation.