Set up AI agent token exchange

Identity Engine

Learn how to configure token exchange for AI agents so that you can securely request and use credentials (ID-JAG, secrets, service accounts, or third-party access tokens) to access protected resources on behalf of authenticated users, and so that AI agents can securely call each other as part of automated workflows (agent-to-agent).

---

Learning outcomes

• Understand how to set up the token exchange flow for AI agents.

What you need

• An Okta org that's subscribed to Okta for AI Agents

• An Okta admin account with the super admin role

• A registered AI agent in your Okta org. See Add and register AI agents (opens new window).

  Note: If you're using the Connect to another AI Agent resource type, you need two registered AI agents.

• A Resource connection that's configured for each AI agent, defining which resources they're allowed to access. See Connect AI agents to resources (opens new window).

  • If you're connecting to an Okta custom authorization server, define the custom scopes for each resource app where you're requesting access. These scopes specify what permissions the token exchange grants in the final access token.

• User access or machine access (opens new window) configured for each AI agent, defining the users, apps, and other AI agents that can authorize the AI agent to act on their behalf. See the Configure user access or Configure machine access sections of the Add AI agents manually (opens new window) page.

---

Overview

You've registered an AI agent (opens new window), and configured the access (opens new window) that you require. Configuring this access defines the users, apps, and other AI agents that can authorize an AI agent to act on their behalf. See Agent-to-agent connections (opens new window).

You've also created resource connections (opens new window) that define the AI agent's access to your org's resources. Now, the agent must obtain the actual tokens or credentials to perform tasks.

Note: The connectionType (opens new window) property in the AI Agent Connections API identifies how an AI agent obtains credentials for a resource. Okta uses this value to determine which token exchange flow to apply to the connection.

You can connect an AI agent (opens new window) to the following resource types with the supported connection types.

Resource type	Connection type (connectionType (opens new window))
Agent Gateway	Brokered consent STS (STS_ACCESS_TOKEN (opens new window)) Grants the AI agent access to an Okta-secured endpoint that aggregates tools from multiple MCP servers. This connection uses an access token that's issued by a custom authorization server. See Configure an Agent Gateway > What happens at runtime. Select OAuth STS from the Instructions for dropdown on the right to review the brokered consent STS token exchange flow.
Authorization server	Cross App Access (Authorization server) (IDENTITY_ASSERTION_CUSTOM_AS (opens new window)) Grants the AI agent access to resources that are protected by an Okta custom authorization server. This resource type is supported by Cross App Access (opens new window), which uses ID-JAG (Identity Assertion JWT). Select Authorization server (ID-JAG) from the Instructions for dropdown on the right to review the authorization server token exchange flow.
Secret	Secret (STS_VAULT_SECRET (opens new window)) Uses a static credential for a downstream resource that has been vaulted in Okta Privileged Access (OPA). Select Secret from the Instructions for dropdown on the right to review the OPA vaulted secret STS token exchange flow.
Service account	Service account (STS_SERVICE_ACCOUNT (opens new window)) Uses a static credential for an app that's specified in Universal Directory. This resource is vaulted in Okta Privileged Access. Select Service account from the Instructions for dropdown on the right to review the OPA service account static credentials token exchange flow.
Application	Okta supports the following connections for app resources: Cross App Access (App instance) (IDENTITY_ASSERTION_APP_INSTANCE (opens new window)) Uses the Cross App Access token exchange flow with an app instance in the identity assertion. Select Authorization server (ID-JAG) from the Instructions for dropdown on the right to review the XAA authorization server token exchange flow. Brokered consent STS (STS_ACCESS_TOKEN (opens new window)) Uses a third-party access token that's issued by the third-party authorization server and brokered by Okta. This connection flow requires user consent before an AI agent can act on behalf of the user. Select OAuth STS from the Instructions for dropdown on the right to review the brokered consent STS token exchange flow.
MCP server	Okta supports the following connections for MCP server resources: Cross App Access (MCP server) (IDENTITY_ASSERTION_MCP_SERVER (opens new window)) Uses the Cross App Access token exchange flow with an MCP server as the resource. Select MCP server from the Instructions for dropdown on the right to review the XAA MCP server token exchange flow. Brokered consent STS (STS_ACCESS_TOKEN (opens new window)) Uses a third-party access token that's issued by the third-party authorization server and brokered by Okta. This connection flow requires user consent before an AI agent can act on behalf of the user. Select OAuth STS from the Instructions for dropdown on the right to review the brokered consent STS token exchange flow.
Connect to another AI Agent	Cross App Access (Agent-to-agent) (IDENTITY_ASSERTION_A2A_SERVER (opens new window)) Allows one AI agent to securely invoke another AI agent as a downstream resource protected by an Okta custom authorization server. Through XAA token exchange, the original service identity is maintained across both agents while each obtains specific access tokens for its next connection. Select Agent-to-agent from the Instructions for dropdown on the right to review the AI agent-to-agent token exchange flow.

After the resource type is configured and the AI agent has the token or credentials, it can then perform tasks on the connected resource.

Note: If you're integrating a third-party AI agent platform, such as AWS Bedrock or Azure AI Foundry, see Set up third-party AI Agent token exchange. This guide provides a complete setup walkthrough and a functional demo that you can test end to end.

Note: This guide describes the token exchange when Okta issues the ID-JAG. If your agent holds an ID-JAG issued directly by an external IdP or by another Okta org, it presents that ID-JAG directly to your custom authorization server and doesn't use the org authorization server exchange that's described here. See Configure XAA with an external IdP.

Token exchange flow

The following diagrams and steps describe the

Agent-to-agent

token exchange flow. If you want to change the token exchange flow on this page, select that flow from the Instructions for dropdown list on the right.

Authenticate with Okta

The initial authentication step is different for the two types of access configurations supported by Okta:

• User access: During the initial authentication request to Okta in a user access configuration (opens new window), the AI agent obtains an ID token directly from the authorization server (the IdP).
• Machine access: For machine access (opens new window), another client calls the AI agent and provides its access token for delegation.

Note: Okta also accepts the CIMD URL as the client_id in an OAuth request, just as it would a static client ID. See Use the CIMD client ID in a token request for more detailed information.

User access

1. The AI agent authenticates with an Okta org or custom authorization server and obtains a subject token (T1) that satisfies the access requirement for the AI agent.

   Okta accepts only ID token subject tokens minted for the current requesting client, which is the AI agent. So, the initiating client and the AI agent are the same thing, using the same client credentials during authentication.

Machine access

1. The initiating client authenticates with a custom authorization server and obtains a subject token (access token) that satisfies a delegation link for the AI agent.

   Okta accepts access tokens minted for a different client as subject tokens. This requires a delegation link authorizing that client to delegate to your AI agent, and the token must target your agent's resource URL.

   The OIDC client then passes the access token (subject_token) (T1) to the AI agent so that it can perform actions on the client's behalf.

The exchange flow

The token exchange flow for an AI agent involves the following steps:

2. AI agent 1 sends the subject_token (T1) to the org authorization server and requests an exchange for an ID-JAG token. The server performs validation based on the Resource Connections (opens new window) configuration and returns the requested ID-JAG (T2).
3. Because the requested credential was an ID-JAG, AI agent 1 sends the ID-JAG (T2) to the custom authorization server to exchange it for a usable access token. The server performs validation and returns an access token (T3).
4. AI agent 1 sends that access token (T3) to AI agent 2 so that it can also perform actions on the client or user's behalf through AI agent 1.
5. AI agent 2 sends the subject_token (T3) to the org authorization server and requests an exchange for an ID-JAG token. The server performs validation Resource Connections (opens new window) and returns the requested ID-JAG (T4).
6. Because the requested credential was an ID-JAG, AI agent 2 sends the ID-JAG to the custom authorization server to exchange it for a usable access token. The server performs validation and returns an access token (T5).
7. The AI agent uses the access token to request access to the resource.

Flow specifics

Note: The instructions on this page are for the

Agent-to-agent

token exchange flow. If you want to change the token exchange flow on this page, select that flow from the Instructions for dropdown list on the right.

Initial authentication

To initiate token exchange, the AI agent (user access configuration) or client (machine access configuration) must first authenticate with the appropriate Okta authorization server and obtain a subject token (either an ID token or an access token). This token must satisfy the access requirements for the AI agent.

Note: Okta also accepts the CIMD URL as the client_id in an OAuth request, just as it would a static client ID. See Use the CIMD client ID in a token request for more detailed information.

ID token

To obtain a subject token (subject_token) for a user, the AI agent or client sends a request to the Okta org or custom authorization server to obtain an ID token. Use the Authorization Code with PKCE grant type to obtain an authorization code for the client. See Implement authorization by grant type.

Response

The response contains the access and ID token and the openid scope.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraW...OYqhUp6g",
  "scope": "openid",
  "id_token": "eyJ...vc_JaEQCw"
}

Access token

To obtain a subject token (subject_token) for itself, the client sends a request to an Okta custom authorization server to obtain an access token. Use the Client Credentials grant type to obtain the subject token. See Implement authorization by grant type.

The request includes the resource parameter. The parameter value is the resource URL that's configured on the agent that this client is invoking. For example resource: https://agent1.example.com.

Response

The token returned in the response contains the aud claim. The claim value is the resource URL (https://agent1.example.com) for the AI agent. This is the agent that performs token exchange.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0blJobUY4Q0xTaUdBenlwemJVIiwiYWxnIjoi...",
  "scope": "chat.read+chat.history"
}

Exchange subject token for resource token

Note: The instructions on this page are for the

Agent-to-agent

token exchange flow. If you want to change the token exchange flow on this page, select that flow from the Instructions for dropdown list on the right.

In this step, after Agent 1 receives the access or ID token (T1), Agent 1 sends a POST request to the Okta org authorization server's /token endpoint as the requesting app. This request is to exchange the token for an ID-JAG resource token (T2). This exchange establishes Agent 1 as the immediate actor in the delegation chain while maintaining the original service client as the subject.

This request supports multiple client authentication methods. The example below changes, depending on how the agent was configured to authenticate its identity to Okta. See Add client registration details (opens new window) on the Add AI agents manually page in the help docs.

Note: This request example uses the access token subject token type and public/private key for client authentication. See Client authentication methods (opens new window) for more details on each type of authentication method.

  curl --location --request POST \
    --url 'https://{yourOktaDomain}/oauth2/v1/token' \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --header "Accept: application/json" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "subject_token=eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0bl...." \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:id-jag" \
    --data-urlencode "audience=https://{yourOktaDomain}/oauth2/{authServerId}" \
    --data-urlencode "resource=https://agent2.example.com" \
    --data-urlencode "scope=chat.read+chat.history" \
    --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data-urlencode "client_assertion=eyJhbGciOiJSUzI1NiIsInR5…[jwt]"

Parameter	Description and value
grant_type	Standard OAuth 2.0 token exchange grant. The value must be urn:ietf:params:oauth:grant-type:token-exchange.
subject_token	A valid ID or access token that satisfies a delegation link for the AI agent
subject_token_type	The type of subject token. The value is either urn:ietf:params:oauth:token-type:id_token or urn:ietf:params:oauth:token-type:access_token.
requested_token_type	The type of token being requested. The value must be urn:ietf:params:oauth:token-type:id-jag.
audience	The issuer URL of the resource app's authorization server
resource	The resource URL of Agent 2
scope	A list of scopes at the resource app that's being requested. This defines the permissions for the final access token.
client_assertion_type	The type of assertion for client authentication. The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	A signed JWT used for client authentication. You must sign the JWT using the key created during the AI agent registration. For more information on building the JWT, see JWT with private key (opens new window).

Response

The response contains an ID-JAG token (T2) with Agent 1 identified in the act claim as the immediate actor and the service client identified in the delegated chain.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "Bearer",
  "expires_in": 300,
  "access_token": "eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWV...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag"
}

The ID-JAG contains the following claims:

{
   "scope": "chat.read chat.history",
   "iss": "https://{yourOktaDomain}",
   "sub": "{subjectFromSubjectToken}",
   "aud": "https://{yourOktaDomain}/oauth2/{authServerId}",
   "iat": "1780596934 // 12:15:34 PM",
   "exp": "1780597234 // 12:20:34 PM",
   "jti": "IDAAG.tAO20ExqeUlh6VcpyQxTJ42fn3vDp9E3xR5Iq3Y79pY",
   "sub_profile": "service",
   "resource": "https://agent2.example.com",
   "act": {
     "sub": "{agent1ClientId}",
     "sub_profile": "ai_agent",
     "act": {
        "sub": "{initiatingClientId}",
        "sub_profile": "service"
      }
    }
}

Claim	Actor
act.sub	Agent 1, the immediate actor
act.act.sub	The original client that initiated the flow

Exchange ID-JAG for access token

After receiving the ID-JAG, Agent 1 sends a POST request to the custom authorization server's /token endpoint to exchange the ID-JAG (T2) for an access token (T3) that can be used to invoke Agent 2.

  curl --location --request POST \
    --url 'https://{yourOktaDomain}/oauth2/{authServerId}/v1/token' \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --header "Accept: application/json" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
    --data-urlencode "assertion=eyJraWQiOiJuc3MwV3UyblE4...[jwt-id-jag]" \
    --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data-urlencode "client_assertion=eyJhbGciOiJSUzI1NiIsInR5...[jwt]"

Parameter	Description and value
grant_type	The value must be urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	The ID-JAG received in the Exchange subject token for resource token response.

Response

The response contains an access token (T3) with the same delegation chain context, which Agent 1 passes to Agent 2.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0blJobUY4Q0xTaUdBenlwemJVIiwiYWxnIjoi...",
  "scope": "chat.read+chat.history"
}

The access token contains the following claims:

{
  "iss": "https://{yourOktaDomain}/oauth2/{authServerId}",
  "sub": "0oa9jh6hizeR7uMag0g7",
  "aud": "https://agent2.example.com",
  "iat": 1780596935,
  "exp": 1780600535,
  "scope": "chat.read chat.history",
  "sub_profile": "service",
  "act": {
    "sub": "{agent1ClientId}",
    "sub_profile": "ai_agent",
    "act": {
      "sub": "{initiatingClientId}",
      "sub_profile": "service"
    }
  }
}

Claim	Actor
act.sub	Agent 1, the immediate actor
act.act.sub	Original service client that initiated the flow.

Agent 2 exchanges token for ID-JAG

In this step, Agent 2 receives the access token (T3) from Agent 1 and exchanges it at the org authorization server for an ID-JAG token (T4). Agent 2 also adds itself to the actor chain. The ID-JAG now reflects Agent 2 as the immediate actor, with Agent 1 in the delegated chain, and the original service client as the origin.

  curl --request POST https://{yourOktaDomain}/oauth2/v1/token \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "subject_token=eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0blJobUY4Q0xTaU..." \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:id-jag" \
    --data-urlencode "audience=https://{yourOktaDomain}/oauth2/{authServerId}" \
    --data-urlencode "scope=chat.read+chat.history" \
    --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data-urlencode "client_assertion=eyJhbGciOiJSUzI1NiIsInR5...[jwt]"

Response

The response contains an ID-JAG token (T4) with the expanded delegation chain showing Agent 2 as the immediate actor.

{
  "token_type": "Bearer",
  "expires_in": 300,
  "access_token": "eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0blJobUY4Q0xTaUdBenlwemJVIiwiYWxnIjoi…",
  "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag"
}

The ID-JAG contains the following claims:

{
  "iss": "https://{yourOktaDomain}",
  "sub": "0oa9jh6hizeR7uMag0g7",
  "aud": "https://{yourOktaDomain}/oauth2/{authServerId}",
  "iat": 1780597035,
  "exp": 1780597335,
  "jti": "IDAAG.FhYRSbhaXljvZIn71hCBN6FKreFgeYgDgm62TkidWqo",
  "scope": "chat.read chat.history",
  "sub_profile": "service",
  "act": {
    "sub": "{agent2ClientId}",
    "sub_profile": "ai_agent",
    "act": {
      "sub": "{agent1ClientId}",
      "sub_profile": "ai_agent",
      "act": {
        "sub": "{initiatingClientId}",
        "sub_profile": "service"
      }
    }
  }
}

Claim	Actor
act.sub	Agent 2, the immediate actor
act.act.sub	Agent 1
act.act.act.sub	The original service client that initiated the flow

Agent 2 exchanges ID-JAG for token

Agent 2 exchanges the ID-JAG (T4) at the custom authorization server for a final access token (T5) that it can use to access the downstream resource.

  curl --request POST https://{yourOktaDomain}/oauth2/{authServerId}/v1/token \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --header "Accept: application/json" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
    --data-urlencode "assertion=eyJraWQiOiJuc3MwV3UyblE4...[jwt-id-jag]" \
    --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data-urlencode "client_assertion=eyJhbGciOiJSUzI1NiIsInR5...[jwt]"

Response

The response contains a final access token (T5) with the complete delegation chain, which Agent 2 uses to access the downstream resource.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraWQiOiJQLVgxeC1ITWtuSThPS0lUeE5TWVlsMHR0blJobUY0Q0xTaUdBenlwemJVIiwiYWxnIjoi...",
  "scope": "chat.read+chat.history"
}

The access token contains the following claims:

{
  "iss": "https://{yourOktaDomain}/oauth2/{authServerId}",
  "sub": "0oa9jh6hizeR7uMag0g7",
  "aud": "https://{finalResource}.example.com",
  "iat": 1780597035,
  "exp": 1780600635,
  "scope": "chat.read chat.history",
  "sub_profile": "service",
  "act": {
    "sub": "{agent2ClientId}",
    "sub_profile": "ai_agent",
    "act": {
      "sub": "{agent1ClientId}",
      "sub_profile": "ai_agent",
      "act": {
        "sub": "{initiatingClientId}",
        "sub_profile": "service"
      }
    }
  }
}

Claim	Actor
act.sub	Agent 2, the immediate actor
act.act.sub	Agent 1
act.act.act.sub	The original service client that initiated the flow

Access the resource

Agent 2 uses the access token (T5) to request access to the downstream resource. The resource server can cryptographically verify the complete delegation chain without trusting any single agent:

• Origin: The original service client that initiated the flow.
• Delegated through: Agent 1 that received the initial token and passed it to Agent 2.
• Immediate actor: Agent 2 that's currently accessing the resource.
• Subject: The original service client or user identity that all actions are performed on behalf of.

This cryptographic audit trail provides complete visibility into the delegation chain and prevents token spoofing or unauthorized modifications.

Revoke tokens

The access token issued by the custom authorization server is a standard Okta access token. Regular access tokens from Okta can be revoked. For details, see Revoke Tokens and User sign out (local app).