Impersonation or Delegation - Amazon Cognito Token Exchange, the act Claim, and Down-Scoping

First Published:
Last Updated:

When backend services or AI agents call other APIs on behalf of a user, a common approach is to simply forward the user's access token downstream. Amazon Cognito user pools added support for OAuth 2.0 token exchange (RFC 8693) in November 2026. With this feature, services can exchange the user's token for a new token with a limited scope, directed to a single destination, before calling downstream services.

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:

Table of Contents

  1. 1. Scope and Assumptions
  2. 2. Exchanging Instead of Forwarding
  3. 3. Impersonation and Delegation
  4. 4. What Is Narrowed
  5. 5. What the Issued Token Is Bound To
  6. 6. External IdP Tokens and the Lambda Trigger
  7. 7. What Cognito Does Not Handle
  8. 8. Adjacent Token Exchanges
  9. 9. Decisions Before You Stop Forwarding
  10. 10. Where the Sources Disagree and What They Do Not Say
  11. 11. Failure Modes
  12. 12. Frequently Asked Questions About Amazon Cognito Token Exchange
  13. 13. Summary
  14. 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 GetDerivedToken operation, which can be called directly via the AWS SDK or through the token endpoint's token-exchange grant type.
  • If an actor token is not included, the issued token will not contain an act claim, and downstream services will be unable to distinguish the request from one made directly by the user. Including an actor token adds an act claim that identifies the intermediary.
  • The act claim 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_act claim 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 act claim 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 ArticleDescription
subject tokenAn existing token that represents a user; it serves as the basis for exchange.
actor tokenA token representing the service or intermediary that performs the exchange. Its use is optional.
issued tokenA new access token or ID token issued by Cognito as a result of the exchange.
impersonationAn exchange performed without an actor token. The issued token appears as if the user directly initiated the action.
delegationAn exchange performed with an actor token. The issued token includes the act claim, indicating an intermediary.
intermediaryA service or agent that calls downstream services on behalf of a user.
downstream serviceAn API or service that receives and validates the issued token.
Essentials feature plan, Plus feature planFeature 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 GetDerivedToken and CreateUserPoolClient operations.
  • "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 the GetDerivedToken operation. There are two ways to call it.

MethodRequest FormatUser Pool Domain
AWS SDKDirectly call GetDerivedTokenNot required
Token EndpointSend a POST request to /oauth2/token with grant_type set to urn:ietf:params:oauth:grant-type:token-exchangeRequired

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, use ALLOW_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 GetDerivedToken method 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 tokenNot presentIdentifies the intermediary
Request as seen by the downstream serviceIndistinguishable from a request made directly by the userClearly indicates that the request was made on behalf of the user by an intermediary
Policies specific to the intermediaryCannot be applied (this article's inference)Can be applied by examining the act claim
Audit logs of the downstream serviceAppear 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 flowALLOW_TOKEN_EXCHANGE_IMPERSONATIONALLOW_TOKEN_EXCHANGE_DELEGATION

What a Downstream Service Sees - Impersonation and Delegation
What a Downstream Service Sees - Impersonation and Delegation
When a token is issued for impersonation, the downstream service's audit logs will not reflect that an intermediary was involved. The downstream service only sees the token's claims, and those claims do not indicate the presence of an intermediary (this article's inference). If you need to record that an intermediary was involved, you must use delegation, or the service performing the exchange must record that information itself. Section 10.2 covers how Cognito logs the exchange itself.

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 of act 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.

How Cognito Derives the Issued Token
How Cognito Derives the Issued Token
The authorized scope of the application client making the exchange request functions as the third set. If the scope granted to the application client used for the exchange is limited to what downstream services require, then the scope produced by that exchange will also be limited to those scopes (this article's inference).

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

The GetDerivedToken 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 CapabilitiesTrigger 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 8693 may_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 an OperationNotEnabledException. 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 calls GetDerivedToken. 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 the GetClientToken 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_IMPERSONATION to application clients that must not use impersonation (see Section 2.4).
  • What to Allow the Intermediary: The act claim 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 GetDerivedToken API reference states that Audiences and Resources cannot 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 missing TokenGeneration_TokenExchange from the table listing trigger sources. The description of grant_type on 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 act claim on an issued token will be nested when the subject token already has an act claim.
  • Which application client's ID is included in the client_id claim 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. The GetDerivedToken operation is in the list of actions in the API reference. However, the contents of the GetDerivedToken event are not described in the sources read.

11. Failure Modes

SymptomCauseReference
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 an act 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?

The act 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 the may_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 GetDerivedToken with 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 act claim, and downstream services will be unable to distinguish the request from the user's direct request. With an actor token, act identifies the intermediary.
  • The act claim 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_act claim.

14. References



References:
Tech Blog with curated related content

Written by Hidekazu Konishi