Amazon Cognito token exchange explained: GetDerivedToken, AI agents, setup and pricing

Amazon Cognito now supports OAuth 2.0 token exchange (RFC 8693). How GetDerivedToken works, impersonation vs delegation for AI agents, limits and plans.

Nato Lagidze15 November 20269 min read0 viewsAWS
Amazon Cognito token exchange explained: GetDerivedToken, AI agents, setup and pricing

Amazon Cognito now supports OAuth 2.0 token exchange (RFC 8693), announced on 12 November 2026. A backend service or AI agent that receives a user's token can trade it for a new, narrower token for one specific downstream API, instead of forwarding the user's original token. You can call it through the user pool's /oauth2/token endpoint or the new GetDerivedToken API. It needs the Essentials or Plus feature plan and works in every Region where Cognito is available.

This guide covers what token exchange does, how impersonation and delegation differ, how to set it up, the limits in the API reference, and what it costs. Everything is taken from AWS's announcement, developer guide and API reference.

What is Cognito token exchange?

Token exchange is an OAuth 2.0 extension, defined in RFC 8693, that swaps an existing token for a new one. In Cognito's version, your service presents a subject token (the user's existing token). Cognito returns an issued token that is:

  • Down-scoped: its scopes are the intersection of the scopes you ask for, the scopes in the subject token, and the scopes your app client is allowed to issue. It can never add a scope the user didn't already have.
  • Audience-bound: you can bind it to one audience or one resource, each of which must be a resource server registered in your user pool.
  • Short-lived, with no refresh token: Cognito never issues a refresh token in an exchange, so a derived token can't outlive the credential it came from.
  • A normal Cognito token: the result is a standard access or ID token that downstream services validate as usual.

Cognito also checks the subject token's signature, expiry and revocation status (for example after a global sign-out). The user must be enabled and confirmed.

AWS's announcement gives a concrete example: a Model Context Protocol (MCP) server calling a backend API for a user. That's why this launch matters most for teams building AI agents, alongside services like Amazon Bedrock AgentCore and Step Functions as agent tools.

What is the difference between impersonation and delegation?

You choose on each request, simply by whether you include an actor token.

Impersonation Delegation
Actor token sent? No Yes (actor_token / ActorToken)
act claim in issued token None Yes, identifies the intermediary
What the downstream API sees The user acting directly An intermediary acting for the user
App client flow needed ALLOW_TOKEN_EXCHANGE_IMPERSONATION ALLOW_TOKEN_EXCHANGE_DELEGATION
Good for Internal service hops where the caller doesn't matter AI agents, MCP servers, audit trails, agent-specific policies

With delegation, the downstream API can read the act claim to apply different rules to agent requests, such as blocking deletes. It can also log that an agent, not the user, made the call.

One gap to note: Cognito doesn't currently issue or evaluate the RFC 8693 may_act claim, which an issuer would use to say in advance which actors may act for a user. Today, that control lives in your app client settings and your own code.

Which token method should I use?

This decision table covers the four common patterns:

Your situation Use
A service calls another service for a signed-in user and should only get the scopes that API needs Token exchange (impersonation)
An AI agent or MCP server acts for a user, and the API must know it was the agent Token exchange (delegation)
A backend job calls an API with no user involved Machine-to-machine (client credentials / GetClientToken)
You currently forward the user's original access token to every downstream service Move to token exchange. Forwarding gives each service more scope and a broader audience than it needs

AWS draws the same line: token exchange derives a user token, while M2M authorization authorises an application.

How do I set up Cognito token exchange?

Prerequisites

  1. A user pool on the Essentials or Plus feature plan.
  2. An app client whose ExplicitAuthFlows include ALLOW_TOKEN_EXCHANGE_IMPERSONATION, ALLOW_TOKEN_EXCHANGE_DELEGATION, or both.
  3. Every audience or resource you request registered as a resource server in the pool.
  4. A user pool domain, if you use the /oauth2/token endpoint. The SDK route doesn't need one.
  5. For tokens from an external OIDC or SAML identity provider: the IdP is registered on the pool, the user is already a linked user, and you pass the provider name. Token exchange doesn't create new users.
  6. Token exchange enabled for your account. If it isn't, the call returns OperationNotEnabledException.

Option 1: the token endpoint

POST to /oauth2/token with the token-exchange grant. Authenticate the client the same way as other grants (client_secret_basic or client_secret_post). This is AWS's documented example request:

POST /oauth2/token HTTP/1.1
Host: example-domain.auth.us-west-2.amazoncognito.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64Encoded(client_id:client_secret)

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=eyJra456defEXAMPLE&
subject_token_type=urn:ietf:params:oauth:token-type:access_token&
audience=solar-system-data&
scope=solar-system-data/asteroids.add

For delegation, add actor_token and actor_token_type. For external-IdP tokens, add subject_token_provider_name or actor_token_provider_name. Those two provider-name parameters are Cognito extensions, not part of RFC 8693.

Option 2: the GetDerivedToken API (AWS SDK)

The request needs ClientId, SubjectToken and SubjectTokenType, plus ClientSecret for a confidential client. This is AWS's documented impersonation example:

{
    "ClientId": "1example23456789",
    "ClientSecret": "exampleClientSecret123EXAMPLE",
    "SubjectToken": "eyJra456defEXAMPLE",
    "SubjectTokenType": "ACCESS_TOKEN",
    "Audiences": [ "solar-system-data" ],
    "Scopes": [ "solar-system-data/asteroids.add" ]
}

A delegation exchange returns an access token whose decoded payload includes the actor, as in AWS's example:

{
    "sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "token_use": "access",
    "scope": "solar-system-data/asteroids.add",
    "aud": "solar-system-data",
    "act": {
        "sub": "service-a-client-id"
    },
    "exp": 1735689600,
    "iat": 1735686000
}

Customising the issued token

If your pool has a pre token generation Lambda trigger, it runs on exchanges with triggerSource set to TokenGeneration_TokenExchange. The function can add, suppress or override claims, suppress scopes, or deny the exchange by returning an error. It can't add scopes. It receives the resolved user's attributes, not the raw token strings.

What are the GetDerivedToken limits?

From the API reference:

Parameter Limit or valid values
SubjectTokenType ACCESS_TOKEN, ID_TOKEN, SAML2
ActorTokenType ACCESS_TOKEN, ID_TOKEN, SAML2
RequestedTokenType ACCESS_TOKEN or ID_TOKEN (Cognito can't issue SAML)
Audiences / Resources Max 1 item each, and you can't send both in one request
Scopes Max 50; if omitted, you get the subject token's scopes
Subject/actor token length Up to 131,072 characters
Response IssuedToken, IssuedTokenType, ExpiresIn (seconds), Scopes, TokenType

Errors to handle include NotAuthorizedException, InvalidParameterException, UserNotFoundException, TooManyRequestsException, OperationNotEnabledException (also thrown in secondary replica Regions) and ForbiddenException when an AWS WAF web ACL blocks the request.

Because no refresh token comes back, cache derived tokens until shortly before ExpiresIn and request a new one when they expire.

How much does Cognito token exchange cost?

AWS hasn't published a separate price for token exchange. The Cognito pricing page doesn't mention it or GetDerivedToken. The cost comes from the feature plan it needs:

Feature plan Price per MAU (first tier) Free tier Token exchange?
Lite $0.0055 10,000 MAUs No
Essentials $0.015 10,000 MAUs Yes
Plus $0.020 None Yes

M2M client-credentials tokens are billed separately, per successful token request ($0.00225 in US East (N. Virginia) in AWS's example), with no free tier. We haven't been able to confirm from AWS whether exchanged tokens are ever billed like M2M requests. Check Cost Explorer after a test month if your volumes are high. Our AWS Free Tier guide covers how to set budget alerts before you experiment.

What are developers saying?

We looked for Reddit and forum discussion of the launch and found no substantial community threads yet. We won't quote reactions we couldn't verify. Search suggestions show people asking:

  • "Does Cognito support token exchange?" (yes, since 12 November 2026)
  • "AWS Cognito token exchange" setup and examples

One source of confusion: an older AWS sample repo, sample-cognito-oauth2-token-exchange, builds an RFC 8693-style flow by hand with two user pools, custom-auth Lambdas and API Gateway. That pattern predates the native feature. For new projects, start with GetDerivedToken or the token endpoint. Its production notes still apply, though: restrict the audience, keep client secrets server-side and enforce per-user authorisation at the resource.

Editor's take

This is a small launch that fixes a real problem. Most "agent calls an API for a user" setups today either forward the user's full token or mint tokens in custom code, and both are hard to audit. Native down-scoping, audience binding, no refresh tokens and an act claim give you a clean, standards-based default. Two caveats: you need Essentials or Plus, and Cognito doesn't support may_act yet. Delegation over impersonation is the better default for AI agents, because the downstream API can always tell the agent apart from the user. If you're also tidying up secrets for these services, see our guide to Secrets Manager cross-account replication. For more AWS infrastructure news this week, see our explainer on Amazon's proposed Walla Walla data center.

FAQ

Does Cognito support token exchange?

Yes. Since 12 November 2026, Amazon Cognito user pools support OAuth 2.0 token exchange (RFC 8693) through the /oauth2/token endpoint and the GetDerivedToken API.

What is GetDerivedToken in Cognito?

It's the Cognito API operation that performs token exchange. You present a subject token (and optionally an actor token) and receive a new access or ID token scoped and bound to one downstream audience or resource.

Which Cognito plans support token exchange?

The Essentials and Plus feature plans. The Lite plan doesn't support it.

Does Cognito token exchange return a refresh token?

No. A token exchange never issues a refresh token, so derived tokens expire on their own.

What is the act claim in a Cognito token?

In a delegation exchange, the act claim identifies the intermediary (for example, an agent's app client) acting for the user, so downstream services can tell agent requests from direct user requests.

Can I exchange a SAML or OIDC token with Cognito?

Yes, if the IdP is registered on your user pool, the user is already a linked user, and you pass the provider name. Cognito issues only access or ID tokens, not SAML.

Is Cognito token exchange the same as client credentials?

No. Token exchange derives a token for a user. Client credentials (M2M) authorises an application with no user, and is billed per token request.

Is Cognito token exchange available in all Regions?

AWS says it's available in all AWS Regions where Amazon Cognito is available.

Sources

Featured image: attendees in the AWS expo hall at AWS re:Invent (an event photo, not a depiction of Cognito). Image: Amazon. Source

Share:

Comments

Leave a comment