Impersonation or Delegation - Amazon Cognito Token Exchange, the act Claim, and Down-Scoping
First Published:
Last Updated:
This article addresses the question of who, from the downstream service's point of view, appears to have acted when the exchanged token is used, and what is narrowed and what remains bound to the original credential. Based on the available documentation, the answer is as follows: If the exchange is performed without an actor token, the resulting token will not include an
act claim, and the downstream service will be unable to distinguish the request as originating from someone other than the original user (impersonation). Conversely, if an actor token is included, the act claim indicates an intermediary (delegation). The act claim only identifies the intermediary; it does not represent the intermediary's permissions. The scope cannot be extended, and refresh tokens are not issued.This article does not cover the RFC 8693 specification, a beginner's introduction to Cognito, or pricing. This article is based on documentation and has not been tested in a practical environment. The information presented was verified on November 19, 2026.
Related articles on this site:
- Identity Lifecycle for AI Agents - Registration, Delegated Authorization, Access Review, and What Retirement Leaves Behind
- User Pool Sessions in Amazon Cognito - SSO and Token Sessions, the Per-User Limit, and What Revocation Does Not Reach
- Agent Interoperability Architecture on AWS - Cross-Runtime Agents with A2A, MCP, and Amazon Bedrock AgentCore Gateway
- Querying Glue Iceberg Tables with a Partner's OIDC Token - Token Exchange at AWS Sign-In, One Role, and Lake Formation
- Browser-Based Apps and Cross-Device Flows on Amazon Cognito - RFC 10017 and RFC 10027 Mapped to App Client Settings
- Where AI Agent Authorization Standards Stand - RFCs, IETF Working Group Documents, Individual Drafts, and Specifications from Other Bodies
- AWS History and Timeline regarding Amazon Cognito - Overview, Functions, Features, Summary of Updates, and Introduction
Table of Contents
- 1. Scope and Assumptions
- 2. Exchanging Instead of Forwarding
- 3. Impersonation and Delegation
- 4. What Is Narrowed
- 5. What the Issued Token Is Bound To
- 6. External IdP Tokens and the Lambda Trigger
- 7. What Cognito Does Not Handle
- 8. Adjacent Token Exchanges
- 9. Decisions Before You Stop Forwarding
- 10. Where the Sources Disagree and What They Do Not Say
- 11. Failure Modes
- 12. Frequently Asked Questions About Amazon Cognito Token Exchange
- 13. Summary
- 14. References
1. Scope and Assumptions
This chapter defines the intended audience for this article, the terminology used, and the sources read. The key conclusions are as follows:- Token exchange involves converting a user's token (the subject token) into a new token for downstream services (the issued token). Cognito performs this exchange through the
GetDerivedTokenoperation, which can be called directly via the AWS SDK or through the token endpoint'stoken-exchangegrant type. - If an actor token is not included, the issued token will not contain an
actclaim, and downstream services will be unable to distinguish the request from one made directly by the user. Including an actor token adds anactclaim that identifies the intermediary. - The
actclaim solely identifies the intermediary; the downstream service determines the permissions granted to that intermediary. - The scope of the issued token is the intersection of three sets: the requested scope, the scope of the subject token, and the scope that the application client is authorized to issue. Scopes cannot be added during the exchange process.
- The exchange process does not issue refresh tokens. Cognito validates the signature, expiration, and revocation status of the subject token before performing the exchange.
- Tokens from external identity providers (IdPs) can be used as subject tokens and actor tokens, provided the user is already linked. However, the exchange process does not create new users. Cognito does not issue SAML tokens.
- Cognito does not issue or evaluate the
may_actclaim as defined in RFC 8693. Determining which intermediaries are authorized to act on behalf of whom must be handled outside of Cognito.
1.1 Who This Article Is For
This article is intended for application and security engineers who are building architectures where backend services or AI agents call other APIs on behalf of users authenticated through Cognito user pools. It particularly assumes readers who are currently passing user access tokens directly downstream. This article assumes readers who believe one of the following:- Using token exchange guarantees that downstream services will always be aware that an intermediary was involved.
- Examining the
actclaim will reveal what the intermediary is allowed to do. - Once exchanged, the token becomes unusable anywhere when the user signs out.
- Using Lambda triggers allows you to add scopes to the exchanged token.
1.2 Terms Used in This Article
This article uses the following terminology, aligning with Cognito documentation:| Term Used in This Article | Description |
|---|---|
| subject token | An existing token that represents a user; it serves as the basis for exchange. |
| actor token | A token representing the service or intermediary that performs the exchange. Its use is optional. |
| issued token | A new access token or ID token issued by Cognito as a result of the exchange. |
| impersonation | An exchange performed without an actor token. The issued token appears as if the user directly initiated the action. |
| delegation | An exchange performed with an actor token. The issued token includes the act claim, indicating an intermediary. |
| intermediary | A service or agent that calls downstream services on behalf of a user. |
| downstream service | An API or service that receives and validates the issued token. |
| Essentials feature plan, Plus feature plan | Feature plans for user pools. There are three options: Lite, Essentials, and Plus. |
The Essentials feature plan is distinct from the Essentials log class within Amazon CloudWatch Logs.
In this article, impersonation is the term used in RFC 8693 and the Cognito documentation, and it does not carry a malicious connotation. It refers to a scenario where a properly configured application client obtains a token that appears to originate from the user themselves, based on the user's existing token.
1.3 Sources and the Date Checked
This article read the following sources. The statements in the sources were checked on November 19, 2026.- The "Exchanging tokens for downstream services" page of the Amazon Cognito Developer Guide.
- The following pages of the Amazon Cognito Developer Guide: "Understanding the access token," "Verifying JSON web tokens," "Ending user sessions with token revocation," "Scopes, M2M, and resource servers," "Pre token generation Lambda trigger," "Application-specific settings with app clients," "User pool feature plans," "The token endpoint," "Managing user pool token expiration and caching," and "Amazon Cognito logging in AWS CloudTrail."
- The Amazon Cognito User Pools API Reference, specifically the
GetDerivedTokenandCreateUserPoolClientoperations. - "What's New" (November 12, 2026), which announced that Amazon Cognito now supports OAuth 2.0 token exchange.
- RFC 8693 (OAuth 2.0 Token Exchange).
This article has not been tested with actual implementations. The content presented here is based on the statements in the sources read and the inferences drawn from that information. Any inferences will be clearly identified as such.
The introduction of token exchange was announced on November 12, 2026, in the "What's New" post. As of November 19, 2026, there is no mention of token exchange in the Developer Guide's Document History. Therefore, the date this article gives for token exchange is the date of the "What's New" announcement.
2. Exchanging Instead of Forwarding
2.1 Why Forwarding Is the Problem
The "Exchanging tokens for downstream services" page of the developer guide states the following:With Amazon Cognito user pools, when your service receives a request from a user, it can exchange the user's token for a new token. The new token is narrowed in scope and bound to the audience of a specific downstream service. Your service doesn't forward the user's original token, which might be broader than the downstream service needs or intended for a different audience.
When a user's access token is forwarded, downstream services may receive tokens with scopes that are unnecessary for those services. They may also receive tokens intended for a different service entirely. Token exchange addresses this by converting those tokens into tokens with only the scopes required by the downstream service and restricted to a single destination.
2.2 Three Tokens
The exchange process involves three tokens:- Subject token: An existing token representing the user. This is mandatory.
- Actor token: A token representing the service performing the exchange. This is optional.
- Issued token: A new token returned by Cognito.
The page describes the issued token as follows:
The issued token is a standard Amazon Cognito access token or ID token that the downstream service validates the same way it validates any user pool token.
Downstream services validate the issued token using the same process as for any other user pool token. Downstream services do not need to implement a new validation mechanism specifically for the issued token (this article's inference).
2.3 Two Entry Points
Cognito performs token exchange using theGetDerivedToken operation. There are two ways to call it.| Method | Request Format | User Pool Domain |
|---|---|---|
| AWS SDK | Directly call GetDerivedToken | Not required |
| Token Endpoint | Send a POST request to /oauth2/token with grant_type set to urn:ietf:params:oauth:grant-type:token-exchange | Required |
At the token endpoint, the application client is authenticated using either
client_secret_basic or client_secret_post, just like with other grant types. When including an actor token, add the actor_token and actor_token_type parameters. For tokens from external IdPs, include either subject_token_provider_name or actor_token_provider_name. The page states that these two parameters are Cognito extensions and are not defined in RFC 8693.The following parameters are required in the
GetDerivedToken request: ClientId, SubjectToken, and SubjectTokenType. Confidential clients must also provide ClientSecret. To include an actor token, add the ActorToken and ActorTokenType parameters. The developer guide provides the following example request.{
"ClientId": "1example23456789",
"ClientSecret": "exampleClientSecret123EXAMPLE",
"SubjectToken": "eyJra456defEXAMPLE",
"SubjectTokenType": "ACCESS_TOKEN",
"Audiences": [ "solar-system-data" ],
"Scopes": [ "solar-system-data/asteroids.add" ]
}
The values accepted for
SubjectTokenType and ActorTokenType are ACCESS_TOKEN, ID_TOKEN, and SAML2. The RequestedTokenType parameter, which specifies the type of token to be issued, only accepts ACCESS_TOKEN and ID_TOKEN.2.4 Prerequisites
The "Prerequisites" section lists the following six requirements:- The user pool must be on the Essentials or Plus feature plan.
- The application client must have an authentication flow that matches the semantics it uses. For impersonation, use
ALLOW_TOKEN_EXCHANGE_IMPERSONATION; for delegation, useALLOW_TOKEN_EXCHANGE_DELEGATION. It is acceptable to include both. - Token exchange must be enabled on the account. If it is not enabled, the operation will return an
OperationNotEnabledException. - Any audience or resource value that is requested must correspond to a resource server registered in the user pool.
- If exchanging tokens from an external IdP, the IdP must be registered in the user pool, and the subject or actor must already exist as a linked user. The provider name must also be passed along with the token.
- If exchanging tokens at the token endpoint, the user pool must have a domain configured. If using the
GetDerivedTokenmethod in the SDK, a domain is not required.
The two authentication flows are values for
ExplicitAuthFlows in CreateUserPoolClient. The API reference describes each as follows:ALLOW_TOKEN_EXCHANGE_IMPERSONATION – Use this flow to request GetDerivedToken token exchanges without an ActorToken. The issued token represents the subject user directly.
ALLOW_TOKEN_EXCHANGE_DELEGATION – Use this flow to request GetDerivedToken token exchanges that include an ActorToken. The issued token carries an act claim that identifies the intermediary acting on the behalf of the subject.
If an application client only has
ALLOW_TOKEN_EXCHANGE_DELEGATION, it cannot request a token exchange without an actor token. The API reference for GetDerivedToken states that the request fails unless the application client has the authentication flow that matches whether the request includes an actor token. To prevent a client from using impersonation, it can be configured without the ALLOW_TOKEN_EXCHANGE_IMPERSONATION setting (this article's inference).3. Impersonation and Delegation
3.1 Choosing by Whether an Actor Token Is Present
Token exchange has two semantics. The page states that whether an actor token is included with each request determines which one applies.Impersonation
When you don't include an actor token, Amazon Cognito issues a token that represents the user acting directly, with no act claim. A downstream service can't distinguish the request from one that you made as the user directly.
Delegation
When you include an actor token, Amazon Cognito issues a token that carries an act (actor) claim, as defined in RFC 8693. The act claim identifies the intermediary that is acting on the user's behalf and contains identity claims only. A downstream service can inspect the act claim to apply policies specific to the intermediary. It can also record in audit logs that an intermediary, not you acting as the user directly, made the request.
The API reference for
GetDerivedToken also describes the behavior when an actor token is not included, as follows.If you don't present an ActorToken, the issued token appears as if the user acted directly.
In other words, simply using token exchange does not reveal the presence of an intermediary to downstream services. The intermediary is only identified when an actor token is included in the exchange.
3.2 What a Downstream Service Sees
The following table compares how the same request appears to a downstream service under the two semantics:| Impersonation (without actor token) | Delegation (with actor token) | |
|---|---|---|
act claim on the issued token | Not present | Identifies the intermediary |
| Request as seen by the downstream service | Indistinguishable from a request made directly by the user | Clearly indicates that the request was made on behalf of the user by an intermediary |
| Policies specific to the intermediary | Cannot be applied (this article's inference) | Can be applied by examining the act claim |
| Audit logs of the downstream service | Appear the same as if the user directly initiated the action (this article's inference) | Can record that the intermediary initiated the action |
| Application client authentication flow | ALLOW_TOKEN_EXCHANGE_IMPERSONATION | ALLOW_TOKEN_EXCHANGE_DELEGATION |

3.3 What the act Claim Holds
The developer guide provides an example of the decoded payload of an access token issued through delegation, as follows:{
"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
}
In this example,
sub refers to the user, while sub within act refers to the intermediary. The intermediary's sub in this instance is a value that resembles a client ID.The guide states that the
act claim contains identity claims only. While act indicates who performed the mediation, it does not specify what permissions the intermediary possesses. The scope of the issued token is derived from the user's subject token and does not represent the intermediary's permissions (see Section 4.1). If downstream services apply specific policies to the intermediary, those services must maintain a mapping between the value of act and the permissions granted to that intermediary (this article's inference).The "Exchanging tokens for downstream services" page of the developer guide instructs readers to refer to Access token default payload on the "Understanding the access token" page to understand where the
act claim appears in the access token. As of November 19, 2026, the payload example and claim descriptions on that page do not include the act claim. This article follows the example on the "Exchanging tokens for downstream services" page.3.4 What the Specification Side Covers
The distinction between impersonation and delegation, the handling ofact claims, and the treatment of nested act instances are defined in RFC 8693. This article does not re-explain the specification itself. The specification side and the treatment of delegation chains as audit records are covered in Section 2.4 and Chapter 4 of the earlier article Identity Lifecycle for AI Agents. This article focuses solely on what Cognito includes within act and what Cognito does not handle.4. What Is Narrowed
4.1 Scopes: The Intersection of Three Sets
The "Security model" section of the page describes the design intent of token exchange as follows:Token exchange is designed so that an exchanged token can never grant more access than the user's original token, and can't outlive the credential that it was derived from.
Regarding scopes, the description for "Down-scoping only" is as follows:
The scopes in the issued token are the intersection of three sets: the scopes you request, the scopes in the subject token, and the scopes the app client is allowed to issue. Token exchange can never add a scope that the subject token didn't already carry. For example, if you request scopes A and B but the subject token carries only A, the issued token includes only A.
The scope of the issued token is limited to scopes that are included in all three of the following sets:
- The scope specified in the exchange request.
- The scope held by the subject token.
- The scope that the application client requesting the exchange is authorized to issue.

The response from
GetDerivedToken returns the scope granted to the issued token in the Scopes field. Since only a portion of the requested scope may be provided, the calling application can determine the actual scope based on this value (this article's inference).4.2 When You Request No Scopes
TheGetDerivedToken API reference describes the behavior when no Scopes are specified as follows:If you don't specify any scopes, Amazon Cognito issues a token with the same scopes as your SubjectToken.
Exchanging tokens without specifying scopes does not restrict the scopes. While the destination may change, a token with the same scope as the user's token will be generated. If the purpose of the exchange is to restrict the scopes, it is necessary to specify
Scopes (this article's inference). From this passage and the passage on the intersection of the three sets in Section 4.1, the sources read do not make clear whether Cognito also narrows the scopes by the scopes the application client is allowed to issue when no scopes are specified (see Section 10.1).4.3 One Audience or One Resource
The page states the following regarding destinations:You can bind the issued token to a single audience and a single resource. Amazon Cognito validates each against a registered resource server in your user pool.
The
GetDerivedToken API reference specifies that both Audiences and Resources are arrays, and each array can contain a maximum of one element. Furthermore, it is not possible to include both in the same request.You can't request both Audiences and Resources in the same request.
In other words, a single exchange can only specify one audience or one resource. While the developer guide can be interpreted as allowing both audiences and resources, the API reference explicitly prohibits including both in the same request (see Section 10.1).
The destination specified must correspond to a resource server registered in the user pool. If a downstream service is not registered as a resource server in the user pool, an exchange targeting that service will not be possible.
The examples in the developer guide show the
aud claim in the issued token matching the value of the requested audience. Downstream services can then verify that the token is intended for them by checking if the aud claim matches their own identifier. The "Verifying JSON web tokens" page states that the API Gateway's JWT authorizer matches the audience to the aud claim if present; otherwise, it uses the client_id claim. When receiving a token at the API Gateway, the authorizer's audience should be set to the destination value specified in the exchange, rather than the application client's ID (this article's inference).5. What the Issued Token Is Bound To
5.1 No Refresh Token
The page states that this process does not issue a refresh token.A token exchange never issues a refresh token. The issued token is short lived and expires on its own, so an exchanged token can't be used to mint new tokens after the original credential is no longer valid.
If the issued token expires, the intermediary will need to initiate another exchange. This requires a valid subject token. If the user's token has expired or been revoked, a new exchange cannot be performed (this article's inference).
The page simply states that the issued token has a short lifespan, without specifying the length or method for determining its validity period. While the developer guide provides an example response with an
expires_in value of 3600, this is merely an example. The response from GetDerivedToken returns the number of seconds until the issued token expires in the ExpiresIn field. The page asks you to plan token caching because a refresh token is not issued, and directs readers to the "Managing user pool token expiration and caching" section.5.2 Subject Token Validation
The page describes how Cognito checks the subject token at the time of the exchange:Amazon Cognito validates the subject token's signature and expiration, and checks it for revocation, for example from a global sign-out. The user that the subject token represents must be enabled and confirmed.
If the subject token has been revoked at the time of the exchange, the exchange is rejected. After a user performs a global sign-out, or after a user is disabled, the intermediary cannot start a new exchange with a token of that user that it still holds.
5.3 After the Original Credential Is Revoked
The inspection described in Section 5.2 refers to the state of the tokens at the time of exchange. The "Exchanging tokens for downstream services" page does not address what happens to previously issued tokens when the subject token is revoked.The "Ending user sessions with token revocation" page states the following about user pool JWTs in general:
User pool JWTs are self-contained with a signature and expiration time that was assigned when the token was created. Revoked tokens can't be used with any Amazon Cognito API calls that require a token. However, revoked tokens will still be valid if they are verified using any JWT library that verifies the signature and expiration of the token.
The "Verifying JSON web tokens" page recommends the following for applications that wish to respect revocation:
Offline signature and expiration checks can't detect revocation on their own. If your application must honor revocation before a token expires, verify the token's status against Amazon Cognito—for example, with an authorized API request—or keep access token lifetimes short.
The issued tokens are also JWTs associated with the user pool. If downstream services only validate the issued token based on its signature and expiration date, it is likely that the issued token will continue to pass validation even after the user has signed out (this article's inference). The page explains "can't outlive the credential" to mean that, because refresh tokens are not available, it is not possible to create new tokens after the original credential has been invalidated. However, it does not state that previously issued tokens are immediately invalidated. The scope of revocation is covered in Chapter 7 of the earlier article User Pool Sessions in Amazon Cognito.
6. External IdP Tokens and the Lambda Trigger
6.1 Tokens from a Registered External IdP
Tokens issued by Cognito, as well as tokens from external IdPs (OIDC or SAML 2.0) registered in the user pool, can be used as the subject token and the actor token. When providing tokens from an external IdP, it is necessary to also provide the provider name. Cognito will then validate the token based on the configuration for that provider.Regarding external IdP tokens, the page states:
A subject or actor that you resolve through a registered external IdP must already exist as a linked user in your user pool. Token exchange doesn't create a new user. If no linked user exists, the exchange fails. Amazon Cognito issues access tokens and ID tokens as output. It can't issue SAML tokens.
If a user from an external IdP has never signed in to Cognito, and there is no linked user in the user pool, their token cannot be exchanged. This is because the exchange process does not create a user, as a sign-in would. The method for linking external IdP users to user pool users is described in Section 10.2 of the earlier article Amazon Cognito Federation Complete Implementation Guide.
While SAML 2.0 assertions can be used as input (for
SubjectTokenType and ActorTokenType with the SAML2 option), they cannot be used as output. The issued tokens must be either access tokens or ID tokens.6.2 The Pre Token Generation Trigger
If a pre token generation Lambda trigger is configured in the user pool, token exchange will also invoke that trigger. The page describes what the trigger can and cannot do as follows.Your function can add, suppress, or override claims, suppress scopes, or deny the exchange by returning an error. Your function can't add scopes. Amazon Cognito removes any scope that isn't in the exchange's requested or default scope set. The function receives the resolved user's attributes. It doesn't receive the raw subject or actor token strings.
| Trigger Capabilities | Trigger Limitations |
|---|---|
| Adding, suppressing, or overriding claims. | Adding scopes. |
| Suppressing scopes. | Receiving raw strings for the subject token and actor token. |
| Returning an error to reject the exchange. |
Even if the trigger adds scopes in its response, Cognito will remove any scopes that are not included in the scopes requested during the exchange or the default scopes. The trigger cannot expand upon the intersection of the three sets described in Section 4.1.
The trigger can determine that it was invoked from an exchange when
triggerSource is TokenGeneration_TokenExchange. In an exchange, the trigger can make decisions such as rejecting specific intermediaries (this article's inference). However, the trigger only receives the resolved user's attributes, not the raw strings of the tokens. The sources read do not specify which information the trigger receives regarding the actor token (see Section 10.2).As of November 19, 2026, the table of trigger sources on the "Pre token generation Lambda trigger" page does not include
TokenGeneration_TokenExchange. This article follows the description on the "Exchanging tokens for downstream services" page.7. What Cognito Does Not Handle
7.1 The may_act Claim
The page includes the following note on the RFC 8693may_act claim:Amazon Cognito doesn't currently issue or evaluate the RFC 8693 may_act claim, which an original token issuer would use to declare in advance which actors can act on a subject's behalf.
The
may_act claim is intended to allow the original token issuer to pre-declare which intermediaries are permitted to act on behalf of the user. Cognito does not issue or evaluate this claim. In the sources read, Cognito verifies the application client's authentication flow, scope, registered resource server, and the subject token. Cognito does not use the may_act claim to determine whether an intermediary, represented by the actor token, is authorized to act on behalf of the user.This determination must be made outside of Cognito (this article's inference). For example, it could involve segmenting the application clients used in exchanges for each intermediary and limiting the intermediary's capabilities through authentication flows and permitted scopes, rejecting the exchange in the pre token generation trigger, or having downstream services reject requests based on the
act claim. The underlying concept of the may_act claim is described in Section 4.4 of the earlier article Identity Lifecycle for AI Agents.7.2 SAML Output and User Creation
As stated in Section 6.1, Cognito does not issue SAML tokens or create users during an exchange. To exchange tokens for users from an external Identity Provider (IdP), the user must first exist as a linked user.7.3 Account Enablement and OperationNotEnabledException
The "Prerequisites" section states that the account must have token exchange enabled, and if it is not enabled, the system will return anOperationNotEnabledException. However, the API reference for GetDerivedToken describes this exception differently.This exception is thrown when an operation is not available in the current region or for the current user pool configuration. This can occur when attempting to perform operations that are not supported in secondary replica regions.
The sources read do not specify the steps required to enable token exchange on an account, nor do they state whether it is enabled by default. The "What's New" post states that token exchange is available on the Essentials and Plus feature plans in all AWS Regions where Cognito is available. If the
OperationNotEnabledException is returned, it will be necessary to verify the feature plan and the Region, and to confirm that the request did not go to a secondary Region of a multi-Region user pool. If the issue persists, it will likely be necessary to contact AWS (this article's inference).8. Adjacent Token Exchanges
8.1 Token Exchange at AWS Sign-In
AWS Sign-In also supports token exchange. The token exchange feature within AWS Sign-In converts partner OIDC tokens into AWS credentials. In contrast, Cognito's token exchange converts tokens from user pools or external identity providers (IdPs) into user pool tokens. Details regarding the AWS Sign-In implementation are described in the earlier article Querying Glue Iceberg Tables with a Partner's OIDC Token.8.2 On-Behalf-Of Token Exchange in AgentCore Identity
Amazon Bedrock AgentCore Identity includes an on-behalf-of token exchange that agents use when obtaining tokens for downstream services. In a Cognito token exchange, the application itself callsGetDerivedToken. The AgentCore Identity side is covered in Section 5.2 of the earlier article Agent Interoperability Architecture on AWS.8.3 Machine-to-Machine Authorization
The page states that token exchange is distinct from machine-to-machine (M2M) authorization. M2M authorization involves authorizing applications, rather than users. Access tokens obtained through client credentials grants or theGetClientToken operation, used for M2M communication, do not represent a user. Token exchange, on the other hand, is used to create user tokens for downstream services, originating from a user's existing token.9. Decisions Before You Stop Forwarding
Before switching to token exchange, determine the following:- Impersonation or Delegation: If downstream services need to know that an intermediary is acting on behalf of the user, use delegation. With impersonation, the intermediary will not be recorded in the downstream service's audit logs (see Section 3.2). Do not give
ALLOW_TOKEN_EXCHANGE_IMPERSONATIONto application clients that must not use impersonation (see Section 2.4). - What to Allow the Intermediary: The
actclaim simply identifies the intermediary and does not carry its permissions. Specify what the intermediary is allowed to do through the downstream service's configuration, the application client's configuration, or a Lambda trigger (see Sections 3.3 and 7.1). - Whether to Specify a Scope: If a scope is not specified in the exchange, the resulting token will have the same scope as the subject token (see Section 4.2).
- Whether to Register the Downstream Service as a Resource Server: The destination value must correspond to a registered resource server (see Section 4.3).
- To What Extent to Honor Revocation: Validation based solely on signature and expiration date will not reveal whether an issued token has been revoked (see Section 5.3).
- How to Handle Long-Running Processes: Since refresh tokens are not issued, processes that need to continue beyond the expiration of the user's token cannot be sustained through token exchange alone (see Section 5.1) (this article's inference).
The following scenarios may not provide significant benefits from switching to token exchange, or may not be feasible:
- The user pool is using the Lite feature plan, and it is not possible to change the feature plan.
- The downstream service is an external API that cannot be registered as a resource server in the user pool.
- There is no need to inform the downstream service of the intermediary, and the user's token scope and destination already match the downstream service.
10. Where the Sources Disagree and What They Do Not Say
10.1 Where the Sources Disagree
- Audience and Resource: The developer guide states that the issued token can be bound to a single audience and a single resource. The
GetDerivedTokenAPI reference states thatAudiencesandResourcescannot be included in the same request. This article follows the API reference and states that a single exchange targets either one audience or one resource (Section 4.3). - When No Scope is Specified: The API reference states that when no scope is specified, it defaults to the scope of the subject token. The developer guide describes the scope as the intersection of three sets, and in the section on Lambda triggers, it refers to a "requested or default scope set." The sources read do not make clear whether Cognito also narrows the scopes by the application client's allowed scopes when no scope is specified (Section 4.2).
- Meaning of
OperationNotEnabledException: The developer guide states that this exception is returned when token exchange is not enabled on the account. The API reference states that it is returned when the operation is not supported due to Region or user pool settings (Section 7.3). - Other Pages Are Outdated: As of November 19, 2026, the "Understanding the access token" page does not mention
act, and the "Pre token generation Lambda trigger" page is missingTokenGeneration_TokenExchangefrom the table listing trigger sources. The description ofgrant_typeon the "The token endpoint" page also does not include the token-exchange grant. This article follows the "Exchanging tokens for downstream services" page and the API reference.
10.2 What the Sources Do Not Say
- The length of validity for issued tokens and how that duration is determined (Section 5.1).
- How previously issued tokens are handled when the subject token is revoked after an exchange (Section 5.3).
- Whether the
actclaim on an issued token will be nested when the subject token already has anactclaim. - Which application client's ID is included in the
client_idclaim of the issued token. - Whether Lambda triggers receive information about the actor token (Section 6.2).
- The steps to enable token exchange for an account (Section 7.3).
- How the subject and actor involved in an exchange are logged in CloudTrail. The "Amazon Cognito logging in AWS CloudTrail" page states that all operations listed on the "User pool actions" page are recorded as management events, and that some fields, such as tokens, are obscured with
HIDDEN_DUE_TO_SECURITY_REASONS. TheGetDerivedTokenoperation is in the list of actions in the API reference. However, the contents of theGetDerivedTokenevent are not described in the sources read.
11. Failure Modes
| Symptom | Cause | Reference |
|---|---|---|
| The downstream service's audit logs do not show that the agent made the request. | The token was exchanged without an actor token (impersonation). | Section 3.1 |
Even when examining act, it is unclear what permissions are granted to the intermediary. | act only contains claims that identify the intermediary. | Section 3.3 |
| The issued token lacks the requested scope. | The subject token or the scopes the application client is allowed to issue do not include that scope. | Section 4.1 |
| The token was exchanged, but the scope is not restricted. | Scopes were not specified. | Section 4.2 |
Requests with both Audiences and Resources specified fail. | Both cannot be included in the same request. | Section 4.3 |
| The API Gateway's authorizer rejects the issued token. | The authorizer's audience does not match the aud field in the issued token. | Section 4.3 |
| A long-running agent process fails to obtain a token mid-process. | The exchange does not issue a refresh token, and the user's token has expired. | Section 5.1 |
| After the user signs out, downstream services still accept the issued token. | The downstream service is only validating the signature and expiration date. | Section 5.3 |
| Exchange of tokens for users from an external IdP fails. | There is no linked user in the user pool. | Section 6.1 |
| Scopes added via a Lambda trigger are not present in the issued token. | Scopes cannot be added during the exchange process. | Section 6.2 |
An OperationNotEnabledException is returned. | Token exchange is not enabled for the account, or is not available in the Region or for the user pool configuration. | Section 7.3 |
12. Frequently Asked Questions About Amazon Cognito Token Exchange
Does Amazon Cognito token exchange always tell the downstream service that an agent made the request?
No, Amazon Cognito token exchange does not always inform the downstream service that an agent made the request. If the exchange is performed without an actor token, the issued token will not include anact claim, and the downstream service will be unable to distinguish the request from one made directly by the user. The downstream service only recognizes that an agent was involved when the exchange is performed with an actor token.What does the act claim contain?
Theact claim contains only claims that identify the intermediary. In the developer guide's example, the act contains the intermediary's sub. The act does not specify what actions the intermediary is permitted to take.Can a token exchange add scopes?
Scopes cannot be added. The scope of the issued token is the intersection of the requested scope, the scope of the subject token, and the scope that the application client is permitted to issue. The pre token generation Lambda trigger cannot add scopes either.Does a token exchange return a refresh token?
No, it does not. Once the issued token expires, you will need to perform another exchange with a valid subject token.Does Amazon Cognito evaluate the may_act claim?
Amazon Cognito does not evaluate themay_act claim. Cognito neither issues nor evaluates this claim. It is necessary to determine which intermediary is authorized to act on behalf of the user through the application client configuration, Lambda triggers, and downstream services.Which feature plans support token exchange?
The Essentials and Plus feature plans. The "What's New" post states that it is available in all AWS Regions that offer Cognito.Can a token from an external identity provider be exchanged?
Yes, tokens from external identity providers can be exchanged. You can submit tokens from OIDC or SAML 2.0 IdPs registered with the user pool, along with the provider name. However, the user must already exist in the user pool as a linked user. This exchange process does not create new users.13. Summary
- Token exchange converts a user's token into a new token that is narrowed in scope and bound to a single destination. This is achieved by calling
GetDerivedTokenwith the SDK or at the token endpoint. This functionality requires either the Essentials or Plus feature plan. - If an actor token is not included, the issued token will not contain the
actclaim, and downstream services will be unable to distinguish the request from the user's direct request. With an actor token,actidentifies the intermediary. - The
actclaim solely identifies the intermediary. The configuration of downstream services, application clients, or Lambda triggers determines the permissions granted to the intermediary. - The scope is defined as the intersection of three sets and cannot be added to. If no scope is specified, it defaults to the scope of the subject token. The destination is one audience or one resource that corresponds to a registered resource server.
- The exchange process does not issue a refresh token. While the subject token's signature, expiration, and revocation are checked at the time of exchange, validating an issued token solely based on its signature and expiration does not reveal any subsequent revocation status.
- Tokens from external IdPs require a linked user in the user pool, and the exchange process does not create new users. Cognito does not issue SAML tokens, nor does it issue or evaluate the
may_actclaim.
14. References
- Amazon Cognito Developer Guide: Exchanging tokens for downstream services
- Amazon Cognito Developer Guide: Understanding the access token
- Amazon Cognito Developer Guide: Verifying JSON web tokens
- Amazon Cognito Developer Guide: Ending user sessions with token revocation
- Amazon Cognito Developer Guide: Scopes, M2M, and resource servers
- Amazon Cognito Developer Guide: Pre token generation Lambda trigger
- Amazon Cognito Developer Guide: Application-specific settings with app clients
- Amazon Cognito Developer Guide: User pool feature plans
- Amazon Cognito Developer Guide: The token endpoint
- Amazon Cognito Developer Guide: Managing user pool token expiration and caching
- Amazon Cognito Developer Guide: Amazon Cognito logging in AWS CloudTrail
- Amazon Cognito User Pools API Reference: GetDerivedToken
- Amazon Cognito User Pools API Reference: CreateUserPoolClient
- What's New: Amazon Cognito now supports OAuth 2.0 token exchange
- RFC Editor: RFC 8693 - OAuth 2.0 Token Exchange
References:
Tech Blog with curated related content
Written by Hidekazu Konishi