Cognito token exchange: actor identity and narrower scopes

Check eligibility before treating the announcement as account access

On November 12, 2026, AWS announced OAuth 2.0 Token Exchange for Cognito user pools. A service receiving a user request can obtain a token suited to a downstream service instead of forwarding the original, potentially broader token. The announcement covers every AWS Region where Cognito is available, with eligibility limited to Essentials or Plus.

The developer guide also requires account-level enablement. Regional availability does not establish immediate access for every account, user pool or replica Region. Investigate OperationNotEnabledException against account enablement, user-pool configuration and the target Region.

The current pricing page distinguishes user-pool monthly active user charges and other add-ons; it does not establish a token-exchange-specific numeric price for this article. Do not label exchange free or apply the client-credentials M2M token price. Assess costs for the actual Region, sign-in method and plan.

Choose delegation when the downstream service needs actor identity

The subject token represents the user; the actor token represents the intermediary making the downstream call. Without an actor token, the exchange uses impersonation. Its issued token has no act claim, so the downstream service cannot use that claim to distinguish a direct user action from an intermediary’s action.

Supplying ActorToken and ActorTokenType selects delegation, with the intermediary identified in act. The app client’s ExplicitAuthFlows must enable ALLOW_TOKEN_EXCHANGE_DELEGATION. Impersonation instead requires ALLOW_TOKEN_EXCHANGE_IMPERSONATION; enable both only when both are needed.

The act claim contains identity information. The downstream service still validates the token and enforces its own authorization policies. It is not blanket permission for an agent, and using an AI tool does not make the claim appear automatically.

Omitting Scopes does not automatically reduce access

The GetDerivedToken Scopes contract says that explicit scopes are intersected with the SubjectToken’s scopes and those allowed for the requesting app client. Exchange cannot add a scope absent from the original token.

For example, suppose the original token has orders/read and orders/write, while the downstream service only needs to read orders. Request orders/read explicitly, then inspect the response Scopes and issued token. This hypothetical example explains scope selection; no user-pool call was performed.

The API specifically says that omitting Scopes issues a token with the same scopes as SubjectToken. Completing an exchange therefore does not establish least privilege. Identify the required operations before requesting a token and check the actual grant afterward.

Use either Audiences or Resources

An audience identifies the target service, while a resource identifies a resource server in the user pool. The operating guide gives a general description; the precise GetDerivedToken request contract makes Audiences and Resources mutually exclusive, with at most one value in either array. Do not populate both in one request.

The target must correspond to a registered user-pool resource server. The downstream service must still validate the issued token’s signature, target and permissions. Decoding a field alone is not proof that a request is authorized.

OAuth and SDK requests use different parameter forms

At a user-pool domain’s /oauth2/token endpoint, send an application/x-www-form-urlencoded POST with grant_type set to urn:ietf:params:oauth:grant-type:token-exchange. Token-type parameters use RFC URNs. Authenticate the app client as documented; delegation also needs actor_token and actor_token_type.

Calling GetDerivedToken through an AWS SDK does not require a user-pool domain. Required fields include ClientId, SubjectToken and SubjectTokenType; a confidential app client also supplies ClientSecret. The SDK’s SubjectTokenType uses ACCESS_TOKEN, ID_TOKEN or SAML2. Do not copy an OAuth token-type URN into that field.

Choose an interface and follow its current field names and encoding. This article did not submit token requests or use real credentials. Confirm the app-client and identity-provider configuration in an authorized test environment before integration.

Inspect the actual expiry and error type

Exchange returns no refresh token, and the issued token cannot outlive the credential it derives from. Read the ExpiresIn value in seconds from GetDerivedToken; the documentation’s 3600 example is not a fixed one-hour promise. Caching and reacquisition must account for the original credential’s remaining validity.

When a request fails, retain a sanitized error type and identify the failing stage. The API documents InvalidParameterException for invalid parameters and NotAuthorizedException for authorization failures. ForbiddenException describes an associated AWS WAF web ACL blocking the request, with a documented HTTP status of 400. Do not infer 403 from its name or attribute every failure to the network exit.