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
• Custom scopes defined in your Okta custom authorization server for each resource app where you're requesting access. These scopes specify what permissions the token exchange grants in the final access token. You select these scopes when you connect AI agents to resource connections (opens new window).
• A registered AI agent in your Okta org. See Add and register AI agents (opens new window).

  Note: If you're using the agent-to-agent connection 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).

  Note: The Resource server resource type in this guide covers both the Application and MCP Server resource types. These types support the brokered consent Security Token Service (STS) flow.

• 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.

You can connect an AI agent (opens new window) to the following resource types:

• Authorization server: 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).

• Secret: Uses a static credential for a downstream resource that has been vaulted in Okta Privileged Access.

• Service account: Uses a static credential for an app that's specified in Universal Directory. This resource is vaulted in Okta Privileged Access.

• Resource server (STS): Uses a third-party access token that's issued by the third-party authorization server and brokered by Okta. This resource type requires user consent before an AI agent can act on behalf of the user.

• Agent-to-agent: Allows one AI agent to securely invoke another AI agent as a downstream resource protected by an Okta custom authorization server. Through token exchange, the original service identity is maintained across both agents while each obtains specific access tokens for its next connection. This resource type is supported by Cross App Access, which uses the Identity Assertion JWT (ID-JAG).

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

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.

Token Exchange flow

The following diagram describes the

Resource server (STS)

resource type. If you want to change the resource type on this page, select that type from the Instructions for dropdown list on the right.

During the initial authentication request in a user access configuration (opens new window), the AI agent must obtain an ID token directly. For machine access (opens new window), another client calls the AI agent and provides its access token for delegation. So, the initial step is different for these two types of access.

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 passes the access token (subject_token) (T1) to the AI agent so that it can perform actions on the client's behalf.

Token exchange flow

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

2. The AI agent sends a POST /token request to Okta, asking for an access token for a protected resource in the target app. Okta checks to see if it already possesses a valid token for the user and the requested app.
3. If no valid token is found, Okta returns an HTTP 400 Bad Request response to the AI agent. This response contains an error code of interaction_required and a unique interaction_uri.
4. The AI agent receives the interaction_required error and redirects the user's browser to the interaction_uri that's provided by Okta.
5. The user is directed to the app's website, where they're prompted to authorize the connection and grant consent for the AI agent to access their data.
6. After the user grants consent, the app redirects the user's browser back to an Okta endpoint, including a temporary, single-use auth_code in the URL.
7. Okta exchanges the auth_code with the app.
8. Okta receives a new access token and a long-lived refresh token. Okta securely saves these tokens, linking them to the user.
9. After Okta successfully stores the tokens, the user asks the agent to retry the connection. This signals that the consent part of the flow is complete.
10. The AI agent's code retries the original POST /token request from step 3. Because Okta now has the necessary tokens stored, this retry attempt succeeds. Okta responds with an HTTP 200 OK and provides the short-lived access token that the AI agent can use to make its API calls.
11. The AI agent uses the access token to request access to the resource.

Flow specifics

Note: The instructions on this page are for the

Resource server (STS)

resource type. If you want to change the resource type on this page, select that type 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.

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 will perform 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

Resource server (STS)

resource type. If you want to change the resource type on this page, select that type from the Instructions for dropdown list on the right.

In this step, the AI agent sends a POST request to the Okta org authorization server's /token endpoint to exchange the ID token for the resource token.

This request supports multiple client authentication methods. The example below changes, depending on how the agent was configured to authenticate it's 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 --request POST https://{yourOktaDomain}/oauth2/v1/token \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:okta:params:oauth:token-type:oauth-sts" \
    --data-urlencode "subject_token=eyJraWQiOiJz..." \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
    --data-urlencode "client_assertion=eyJhbGci..." \
    --data-urlencode "resource=resource:indicator:from:resource:connection"

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.
client_assertion_type	The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	A signed JWT that's used for client authentication. You must sign the JWT using the key that you created when you registered the AI agent. For more information on building the JWT, see JWT with private key (opens new window).
subject_token_type	The value must be urn:ietf:params:oauth:token-type:id_token.
subject_token	A valid ID token issued to the resource app that's associated with the AI agent
requested_token_type	Standard OAuth 2.0 token exchange grant. The value must be urn:okta:params:oauthtoken-type:oauth-sts.
resource	A resource identifier for the target app. This must match the resource that's configured on the Resource Connection tab.

Response

The response contains the requested resource token.

The response during the token exchange depends on if Okta has a stored token.

Interaction required response

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

{
  "error": "interaction_required",
  "error_description": "The user must authenticate with the authorization server for the request to proceed",
  "interaction_uri": "https://example.okta.com/some/opaque/path"
}

If Okta doesn't have a valid token, it returns an HTTP 400 error. Your agent's logic must handle this by initiating the user consent flow.

To handle this, your app should do the following:

1. Parse the interaction_uri from the JSON response.
2. Redirect the end user's browser to this URL.
3. After the user completes the flow and is redirected back to your app, retry the original /token request.

Token exists response

{
  "issued_token_type": "urn:okta:params:oauth:token-type:oauth-sts",
  "access_token": "eyJhbGciOiJIUzI1NiIsI...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read resource"
}

Your AI agent should use the access_token from this response to make authenticated API calls to the target resource, including it in the Authorization header as a Bearer token.

Revoke tokens

After obtaining an OAuth STS access token through the token exchange flow, the AI agent can revoke that token using the org authorization server's /oauth2/v1/revoke endpoint and the same client credentials that it used for token exchange.

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

POST /oauth2/v1/revoke HTTP/1.1
Host: example.okta.com
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJIUzI1NiIsI...
&token_type_hint=oauth_sts
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGci...

Parameter	Description and value
token	The access_token value from the successful token exchange response.
token_type_hint	The value must be oauth_sts.
client_assertion_type	The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	A signed JWT that's used for client authentication. You must sign the JWT using the key that you created when you registered the AI agent. For more information on building the JWT, see JWT with private key (opens new window).

The endpoint returns 200 OK regardless of whether the token was valid or already expired, to prevent information leaks.

Important: Revoking an OAuth STS token at the Okta /revoke endpoint only removes the access token from Okta's token store. Keep the following behavior in mind:

• If Okta still holds a valid refresh token for the connection, the next token exchange request obtains a new access token automatically.
• If Okta's refresh token is also expired or invalid, the next token exchange request returns an interaction_required response and a new user consent flow is required.
• The access token isn't automatically revoked from the external resource authorization server. If the access token was shared or copied elsewhere, you must revoke it directly with the external provider.