# Understanding user pool JSON web tokens (JWTs) Tokens are artifacts of authentication that your applications can use as proof of OIDC authentication and to request access to resources. The *claims* in tokens are information about your user. The ID token contains claims about their identity, like their username, family name, and email address. The access token contains claims like `scope` that the authenticated user can use to access third-party APIs, Amazon Cognito user self-service API operations, and the [userInfo endpoint](userinfo-endpoint.md). The access and ID tokens both include a `cognito:groups` claim that contains your user's group membership in your user pool. For more information about user pool groups, see [Adding groups to a user pool](cognito-user-pools-user-groups.md). Amazon Cognito also has refresh tokens that you can use to get new tokens or revoke existing tokens. [Refresh a token](amazon-cognito-user-pools-using-the-refresh-token.md) to retrieve a new ID and access tokens. [Revoke a token](amazon-cognito-user-pools-using-the-refresh-token.md#amazon-cognito-identity-user-pools-revoking-all-tokens-for-user) to revoke user access that is allowed by refresh tokens. Amazon Cognito issues tokens as [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)-encoded strings. You can decode any Amazon Cognito ID or access token from `base64url` to plaintext JSON. Amazon Cognito refresh tokens are encrypted, opaque to user pools users and administrators, and can only be read by your user pool. **Authenticating with tokens** When a user signs into your app, Amazon Cognito verifies the login information. If the login is successful, Amazon Cognito creates a session and returns an ID token, an access token, and a refresh token for the authenticated user. You can use the tokens to grant your users access to downstream resources and APIs like Amazon API Gateway. Or you can exchange them for temporary AWS credentials to access other AWS services. ![\[Authentication overview\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-cup2.png) **Storing tokens** Your app must be able to store tokens of varying sizes. Token size can change for reasons including, but not limited to, additional claims, changes in encoding algorithms, and changes in encryption algorithms. When you enable token revocation in your user pool, Amazon Cognito adds additional claims to JSON Web Tokens, increasing their size. The new claims `origin_jti` and `jti` are added to access and ID tokens. For more information about token revocation, see [Revoking tokens](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html). **Important** As a best practice, secure all tokens in transit and storage in the context of your application. Tokens can contain personally-identifying information about your users, and information about the security model that you use for your user pool. **Customizing tokens** You can customize the access and ID tokens that Amazon Cognito passes to your app. In a [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md), you can add, modify, and suppress token claims. The pre token generation trigger is a Lambda function that Amazon Cognito sends a default set of claims to. The claims include OAuth 2.0 scopes, user pool group membership, user attributes, and others. The function can then take the opportunity to make changes at runtime and return updated token claims to Amazon Cognito. Additional costs apply to access token customization with version 2 events. For more information, see [Amazon Cognito Pricing](https://aws.amazon.com/cognito/pricing/). **Topics** + [Understanding the identity (ID) token](amazon-cognito-user-pools-using-the-id-token.md) + [Understanding the access token](amazon-cognito-user-pools-using-the-access-token.md) + [Refresh tokens](amazon-cognito-user-pools-using-the-refresh-token.md) + [Ending user sessions with token revocation](token-revocation.md) + [Verifying JSON web tokens](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md) + [Managing user pool token expiration and caching](amazon-cognito-user-pools-using-tokens-caching-tokens.md) # Understanding the identity (ID) token The ID token is a [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) that contains claims about the identity of the authenticated user, such as `name`, `email`, and `phone_number`. You can use this identity information inside your application. The ID token can also be used to authenticate users to your resource servers or server applications. You can also use an ID token outside of the application with your web API operations. In those cases, you must verify the signature of the ID token before you can trust any claims inside the ID token. See [Verifying JSON web tokens](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md). You can set the ID token expiration to any value between 5 minutes and 1 day. You can set this value per app client. **Important** When your user signs in with managed login, Amazon Cognito sets session cookies that are valid for 1 hour. If you use managed login for authentication in your application, and specify a minimum duration of less than 1 hour for your access and ID tokens, your users will still have a valid session until the cookie expires. If the user has tokens that expire during the one-hour session, the user can refresh their tokens without the need to reauthenticate. ## ID Token Header The header contains two pieces of information: the key ID (`kid`), and the algorithm (`alg`). ``` { "kid" : "1234example=", "alg" : "RS256" } ``` **`kid`** The key ID. Its value indicates the key that was used to secure the JSON Web Signature (JWS) of the token. You can view your user pool signing key IDs at the `jwks_uri` endpoint. For more information about the `kid` parameter, see the [Key identifier (kid) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.5). **`alg`** The cryptographic algorithm that Amazon Cognito used to secure the access token. User pools use an RS256 cryptographic algorithm, which is an RSA signature with SHA-256. For more information about the `alg` parameter, see [Algorithm (alg) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.4). ## ID token default payload This is a example payload from an ID token. It contains claims about the authenticated user. For more information about OpenID Connect (OIDC) standard claims, see the list of [OIDC standard claims](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). You can add claims of your own design with a [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md). ```
.{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups": [ "test-group-a", "test-group-b", "test-group-c" ], "email_verified": true, "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role", "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "cognito:username": "my-test-user", "middle_name": "Jane", "nonce": "abcdefg", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:roles": [ "arn:aws:iam::111122223333:role/my-test-role" ], "aud": "xxxxxxxxxxxxexample", "identities": [ { "userId": "amzn1.account.EXAMPLE", "providerName": "LoginWithAmazon", "providerType": "LoginWithAmazon", "issuer": null, "primary": "true", "dateCreated": "1642699117273" } ], "event_id": "64f513be-32db-42b0-b78e-b02127b4f463", "token_use": "id", "auth_time": 1676312777, "exp": 1676316377, "iat": 1676312777, "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "email": "my-test-user@example.com" } . ``` **`sub`** A unique identifier ([UUID](cognito-terms.md#terms-uuid)), or subject, for the authenticated user. The username might not be unique in your user pool. The `sub` claim is the best way to identify a given user. **`cognito:groups`** An array of the names of user pool groups that have your user as a member. Groups can be an identifier that you present to your app, or they can generate a request for a preferred IAM role from an identity pool. **`cognito:preferred_role`** The ARN of the IAM role that you associated with your user's highest-priority user pool group. For more information about how your user pool selects this role claim, see [Assigning precedence values to groups](cognito-user-pools-user-groups.md#assigning-precedence-values-to-groups). **`iss`** The identity provider that issued the token. The claim has the following format. `https://cognito-idp..amazonaws.com/` **`cognito:username`** The username of your user in your user pool. **`nonce`** The `nonce` claim comes from a parameter of the same name that you can add to requests to your OAuth 2.0 `authorize` endpoint. When you add the parameter, the `nonce` claim is included in the ID token that Amazon Cognito issues, and you can use it to guard against replay attacks. If you do not provide a `nonce` value in your request, Amazon Cognito automatically generates and validates a nonce when you authenticate through a third-party identity provider, then adds it as a `nonce` claim to the ID token. The implementation of the `nonce` claim in Amazon Cognito is based on [OIDC standards](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). **`origin_jti`** A token-revocation identifier associated with your user's refresh token. Amazon Cognito references the `origin_jti` claim when it checks if you revoked your user's token with the [Revoke endpoint](revocation-endpoint.md) or the [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API operation. When you revoke a token, Amazon Cognito invalidates all access and ID tokens with the same `origin_jti` value. **`cognito:roles`** An array of the names of the IAM roles associated with your user's groups. Every user pool group can have one IAM role associated with it. This array represents all IAM roles for your user's groups, regardless of precedence. For more information, see [Adding groups to a user pool](cognito-user-pools-user-groups.md). **`aud`** The user pool app client that authenticated your user. Amazon Cognito renders the same value in the access token `client_id` claim. **`identities`** The contents of the user's `identities` attribute. The attribute contains information about each third-party identity provider profile that you've linked to a user, either by federated sign-in or by [linking a federated user to a local profile](cognito-user-pools-identity-federation-consolidate-users.md). This information contains their provider name, their provider unique ID, and other metadata. **`token_use`** The intended purpose of the token. In an ID token, its value is `id`. **`auth_time`** The authentication time, in Unix time format, that your user completed authentication. **`exp`** The expiration time, in Unix time format, that your user's token expires. **`iat`** The issued-at time, in Unix time format, that Amazon Cognito issued your user's token. **`jti`** The unique identifier of the JWT. The ID token can contain OIDC standard claims that are defined in [OIDC standard claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims). The ID token can also contain custom attributes that you define in your user pool. Amazon Cognito writes custom attribute values to the ID token as strings regardless of attribute type. **Note** User pool custom attributes are always prefixed with `custom:`. ## ID Token Signature The signature of the ID token is calculated based on the header and payload of the JWT token. Before you accept the claims in any ID token that your app receives, verify the signature of the token. For more information, see Verifying a JSON Web Token. [Verifying JSON web tokens](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md). # Understanding the access token The user pool access token contains claims about the authenticated user, a list of the user's groups, and a list of scopes. The purpose of the access token is to authorize API operations. Your user pool accepts access tokens to authorize user self-service operations. For example, you can use the access token to grant your user access to add, change, or delete user attributes. With [OAuth 2.0 scopes](https://www.rfc-editor.org/rfc/rfc6749#section-3.3) in an access token, derived from the custom scopes that you add to your user pool, you can authorize your user to retrieve information from an API. For example, Amazon API Gateway supports authorization with Amazon Cognito access tokens. You can populate a REST API authorizer with information from your user pool, or use Amazon Cognito as a JSON Web Token (JWT) authorizer for an HTTP API. To generate an access token with custom scopes, you must request it through your user pool [public endpoints](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html). With the Essentials or Plus [feature plan](cognito-sign-in-feature-plans.md), you can also implement a pre token generation Lambda trigger that adds scopes to your access tokens at runtime. For more information, see [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md). A user's access token with the `openid` scope is permission to request more information about your user's attributes from the [userInfo endpoint](userinfo-endpoint.md). The amount of information from the `userInfo` endpoint derives from the additional scopes in the access token: for example, `profile` for all user data, `email` for their email address. A user's access token with the `aws.cognito.signin.user.admin` scope is permission to read and write user attributes, list authentication factors, configure multi-factor authentication (MFA) preferences, and manage remembered devices. The level of access to attributes that your access token grants to this scope matches the attribute read/write permissions you assign to your app client. The access token is a [JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519). The header for the access token has the same structure as the ID token. Amazon Cognito signs access tokens with a different key from the key that signs ID tokens. The value of an access key ID (`kid`) claim won't match the value of the `kid` claim in an ID token from the same user session. In your app code, verify ID tokens and access tokens independently. Don't trust the claims in an access token until you verify the signature. For more information, see [Verifying JSON web tokens](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md). You can set the access token expiration to any value between 5 minutes and 1 day. You can set this value per app client. **Important** For access and ID tokens, don't specify a minimum less than an hour if you use managed login. Managed login sets browsers cookies that are valid for one hour. If you configure an access token duration of less than an hour, this has no effect on the validity of the managed login cookie and users' ability to reauthenticate without additional credentials for one hour after initial sign-in. ## Access token header The header contains two pieces of information: the key ID (`kid`), and the algorithm (`alg`). ``` { "kid" : "1234example=" "alg" : "RS256", } ``` **`kid`** The key ID. Its value indicates the key that was used to secure the JSON Web Signature (JWS) of the token. You can view your user pool signing key IDs at the `jwks_uri` endpoint. For more information about the `kid` parameter, see the [Key identifier (kid) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.5). **`alg`** The cryptographic algorithm that Amazon Cognito used to secure the access token. User pools use an RS256 cryptographic algorithm, which is an RSA signature with SHA-256. For more information about the `alg` parameter, see [Algorithm (alg) header parameter](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.4). ## Access token default payload This is a sample payload from an access token. For more information, see [JWT claims](https://tools.ietf.org/html/rfc7519#section-4). You can add claims of your own design with a [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md). ```
. { "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups":[ "testgroup" ], "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "version":2, "client_id":"xxxxxxxxxxxxexample", "aud": "https://api.example.com", "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use":"access", "scope":"phone openid profile resourceserver.1/appclient2 email", "auth_time":1676313851, "exp":1676317451, "iat":1676313851, "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "username":"my-test-user" } . ``` **`sub`** A unique identifier ([UUID](cognito-terms.md#terms-uuid)), or subject, for the authenticated user. The username might not be unique in your user pool. The `sub` claim is the best way to identify a given user. **`cognito:groups`** An array of the names of user pool groups that have your user as a member. **`iss`** The identity provider that issued the token. The claim has the following format. `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_EXAMPLE` **`client_id`** The user pool app client that authenticated your user. Amazon Cognito renders the same value in the ID token `aud` claim. **aud** The URL of the API that the access token is intended to authorize for. Present only if your application requested a [resource binding](cognito-user-pools-define-resource-servers.md#cognito-user-pools-resource-binding) from your authorization server. **`origin_jti`** A token-revocation identifier associated with your user's refresh token. Amazon Cognito references the `origin_jti` claim when it checks if you revoked your user's token with the [Revoke endpoint](revocation-endpoint.md) or the [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API operation. When you revoke a token, Amazon Cognito no longer validates access and ID tokens with the same `origin_jti` value. **`token_use`** The intended purpose of the token. In an access token, its value is `access`. **`scope`** A list of OAuth 2.0 scopes issued to the signed-in user. Scopes define the access that the token provides to external APIs, user self-service operations, and user data on the `userInfo` endpoint. A token from the [Token endpoint](token-endpoint.md) can contain any scopes that your app client supports. A token from Amazon Cognito API sign-in only contains the scope `aws.cognito.signin.user.admin`. **`auth_time`** The authentication time, in Unix time format, that your user completed authentication. **`exp`** The expiration time, in Unix time format, that your user's token expires. **`iat`** The issued-at time, in Unix time format, that Amazon Cognito issued your user's token. **`jti`** The unique identifier of the JWT. **`username`** The user's username in the user pool. **More resources** + [How to customize access tokens in Amazon Cognito user pools](https://aws.amazon.com/blogs/security/how-to-customize-access-tokens-in-amazon-cognito-user-pools/) ## Access token signature The signature of the access token, signed with the key advertised at the `.well-known/jwks.json` endpoint, validates the integrity of the token header and payload. When you use access tokens to authorize access to external APIs, always configure your API authorizer to verify this signature against the key that signed it. For more information, see [Verifying JSON web tokens](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md). # Refresh tokens You can use the refresh token to retrieve new ID and access tokens. By default, the refresh token expires 30 days after your application user signs into your user pool. When you create an application for your user pool, you can set the application's refresh token expiration to any value between 60 minutes and 10 years. ## Getting new access and identity tokens with a refresh token Amazon Cognito issues refresh tokens in response to successful authentication with the managed login authorization-code flow and with API operations or SDK methods. The refresh token returns new ID and access tokens, and optionally a new refresh token. You can use refresh tokens in the following ways. **GetTokensFromRefreshToken** The [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API operation issues new ID and access tokens from a valid refresh token. You also get a new refresh token if you've enabled refresh token rotation. **InitiateAuth and AdminitiateAuth** The [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) or [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API operations include the `REFRESH_TOKEN_AUTH` authentication flow. In this flow, you pass a refresh token and get new ID and access tokens. You can't authenticate with `REFRESH_TOKEN_AUTH` in app clients with [refresh token rotation](#using-the-refresh-token-rotation) enabled. **OAuth token endpoint** The [token endpoint](token-endpoint.md) in user pools with a [domain](cognito-user-pools-assign-domain.md) has a `refresh_token` grant type that issues new ID, access, and optionally (with [refresh token rotation](#using-the-refresh-token-rotation)) refresh tokens from a valid refresh token. ## Refresh token rotation You can optionally configure refresh token rotation in your app client. With refresh token rotation, your client can invalidate the original refresh token and issue a new refresh token with each token refresh. When this setting is enabled, each successful request in all forms of token refresh return a new ID, access, *and* refresh token. When this setting is disabled, token-refresh requests return new access and ID tokens only and the original refresh token remains valid. The new refresh token is valid for the remaining duration of the original refresh token. You can configure [app clients](user-pool-settings-client-apps.md) to rotate refresh tokens or to carry over the original refresh token. To allow for retries for a brief duration, you can also configure a grace period for the original refresh token of up to 60 seconds. **Things to know about refresh token rotation** + After you enable refresh token rotation, new claims are added in JSON web tokens from your user pool. The `origin_jti` and `jti` claims are added to access and ID tokens. These claims increase the size of the JWTs. + Refresh token rotation isn't compatible with the authentication flow `REFRESH_TOKEN_AUTH`. To implement refresh token rotation, you must disable this authentication flow in your app client and design your application to submit token-refresh requests with the [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API operation or the equivalent SDK method. + With refresh token rotation inactive, you can complete token-refresh requests with either `GetTokensFromRefreshToken` or `REFRESH_TOKEN_AUTH`. + When [device remembering](amazon-cognito-user-pools-device-tracking.md) is active in your user pool, you must provide the device key in `GetTokensFromRefreshToken` requests. If your user doesn't have a confirmed-device key that your application submits in the initial authentication request, Amazon Cognito issues a new one. To refresh tokens in this configuration, you must provide a device key, whether you specified one in `AuthParameters` or received a new one in the authentication response. + You can pass `ClientMetadata` to the pre token generation Lambda trigger in your `GetTokensFromRefreshToken` request. This data, which gets passed to the input event for your trigger, delivers additional context that you can use in the custom logic of your Lambda function. As a security best practice, enable refresh token rotation on your app clients. ------ #### [ Enable refresh token rotation (console) ] The following procedure turns refresh token rotation on or off for your app client. This procedure requires an existing app client. To learn more about creating an app client, see [Application-specific settings with app clients](user-pool-settings-client-apps.md). **To enable refresh token rotation** 1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials. 1. Choose **User Pools**. 1. Choose an existing user pool from the list. 1. Navigate to the **App clients** menu and select an existing app client. 1. Select **Edit** from the **App client information** section of the page. 1. Under **Advanced security configurations**, locate the **Enable refresh token rotation** option. 1. To enable rotation, select the checkbox. To disable rotation, deselect the checkbox. 1. Under **Refresh token rotation grace period**, enter a number of seconds, up to 60, that you want to set as the delay before the rotated-out refresh token is revoked. ------ #### [ Enable refresh token rotation (API) ] Configure refresh token rotation in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API request. The following partial request body turns on refresh token rotation and sets the grace period to ten seconds. ``` "RefreshTokenRotation" : { "Feature" : "ENABLED, "RetryGracePeriodSeconds" : 10 } ``` ------ ## API and SDK token refresh There are two ways to use the refresh token to get new ID and access tokens with the user pools API, depending on whether refresh token rotation is active. In app clients with refresh token rotation active, use the [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API operation. In app clients without refresh token rotation, use the `REFRESH_TOKEN_AUTH` flow of the [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) or [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API operations. **Note** Users can authenticate with user pools in [managed login](cognito-user-pools-managed-login.md) or in custom applications that you build with AWS SDKs and Amazon Cognito API operations. The `REFRESH_TOKEN_AUTH` flow and `GetTokensFromRefreshToken` can both complete token refresh for managed login users. Token refresh in custom applications doesn't affect managed login sessions. These sessions are set in a browser cookie and are valid for one hour. The `GetTokensFromRefreshToken` response issues new ID, access, and optionally refresh tokens, but doesn't renew the managed login session cookie. `REFRESH_TOKEN_AUTH` isn't available in app clients with refresh token rotation enabled. ------ #### [ GetTokensFromRefreshToken ] [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) returns new ID, access and refresh tokens from a request that you authorize with a refresh token. The following is an example request body for `GetTokensFromRefreshToken`. You can submit client metadata to Lambda triggers in requests to this operation. ``` { "RefreshToken": "eyJjd123abcEXAMPLE", "ClientId": "1example23456789", "ClientSecret": "myappclientsecret123abc", "ClientMetadata": { "MyMetadataKey" : "MyMetadataValue" }, } ``` ------ #### [ AdminInitiateAuth/InitiateAuth ] To use the refresh token when refresh token rotation is inactive, use the [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) or [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API operations. Pass `REFRESH_TOKEN_AUTH` for the `AuthFlow` parameter. In the `AuthParameters` property of `AuthFlow`, pass your user's refresh token as the value of `"REFRESH_TOKEN"`. Amazon Cognito returns new ID and access tokens after your API request passes all challenges. The following is an example request body for a token refresh with the `InitiateAuth` or `AdminInitiateAuth` API. ``` { "AuthFlow": "REFRESH_TOKEN_AUTH", "ClientId": "1example23456789", "UserPoolId": "us-west-2_EXAMPLE", "AuthParameters": { "REFRESH_TOKEN": "eyJjd123abcEXAMPLE", "SECRET_HASH": "kT5acwCVrbD6JexhW3EQwnRSe6fLuPTRkEQ50athqv8=" } } ``` ------ ## OAuth token refresh You can also submit refresh tokens to the [Token endpoint](token-endpoint.md) in a user pool where you have configured a domain. In the request body, include a `grant_type` value of `refresh_token` and a `refresh_token` value of your user's refresh token. Requests to the token endpoint are available in app clients with refresh token rotation active and those where it's inactive. When refresh token rotation is active, the token endpoint returns a new refresh token. The following is an example request with a refresh token. ``` POST /oauth2/token HTTP/1.1 Host: auth.example.com Content-Type: application/x-www-form-urlencoded Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw Content-Length: ** client_id=1example23456789&grant_type=refresh_token&refresh_token=eyJjd123abcEXAMPLE ``` ## Revoking refresh tokens You can revoke refresh tokens that belong to a user. For more information about revoking tokens, see [Ending user sessions with token revocation](token-revocation.md). **Note** Revoking the refresh token will revoke all ID and access tokens that Amazon Cognito issued from refresh requests with that token. To sign users out from all current signed-in session, revoke all of their tokens with [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) or [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API requests. After the user is signed out, the following effects happen. + The user's refresh token can't get new tokens for the user. + The user's access token can't make token-authorized API requests. + The user must re-authenticate to get new tokens. Because managed login session cookies don't expire automatically, your user can re-authenticate with a session cookie, with no additional prompt for credentials. After you sign out your managed login users, redirect them to the [Logout endpoint](logout-endpoint.md), where Amazon Cognito clears their session cookie. With refresh tokens, you can persist users' sessions in your app for a long time. Over time, your users might want to deauthorize some applications where they have stayed signed in with their refresh tokens. To sign your user out from a single session, revoke their refresh token. When your user wants to sign themself out from all authenticated sessions, generate a [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) API request . Your app can present your user with a choice like **Sign out from all devices**. `GlobalSignOut` accepts a user's valid–unaltered, unexpired, not-revoked–access token. Because this API is token-authorized, one user can't use it to initiate sign-out for another user. You can, however, generate an [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API request that you authorize with your AWS credentials to sign out any user from all of their devices. The administrator application must call this API operation with AWS developer credentials and pass the user pool ID and the user's username as parameters. The `AdminUserGlobalSignOut` API can sign out any user in the user pool. For more information about requests that you can authorize with either AWS credentials or a user's access token, see [List of API operations grouped by authorization model](authentication-flows-public-server-side.md#user-pool-apis-auth-unauth). # Ending user sessions with token revocation You can revoke refresh tokens and end user sessions with the following methods. When you revoke a refresh token, all access tokens that were previously issued by that refresh token become invalid. The other refresh tokens issued to the user are not affected. **RevokeToken operation** [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) revokes all access tokens for a given refresh token, including the initial access token from interactive sign-in. This operation doesn't affect any of the user's other refresh tokens or the ID- and access-token children of those other refresh tokens. **Revocation endpoint** The [revoke endpoint](revocation-endpoint.md) revokes a given refresh token and all ID and access tokens that the refresh token generated. This endpoint also revokes the initial access token from interactive sign-in. Requests to this endpoint don't affect any of the user's other refresh tokens or the ID- and access-token children of those other refresh tokens. **GlobalSignOut operation** [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) is a self-service operation that a user authorizes with their access token. This operation revokes all of the requesting user's refresh, ID, and access tokens. **AdminUserGlobalSignOut operation** [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) is a server-side operation that an administrator authorizes with IAM credentials. This operation revokes all of the target user's refresh, ID, and access tokens. **Things to know about revoking tokens** + Your request to revoke a refresh token must include the client ID that was used to obtain the token. + 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. + When you create a new user pool client, token revocation is enabled by default. + You can revoke refresh tokens only in app clients with token revocation enabled. + After you enable token revocation, new claims are added in the Amazon Cognito JSON Web Tokens. The `origin_jti` and `jti` claims are added to access and ID tokens. These claims increase the size of the application client access and ID tokens. + When you disable token revocation in an app client where it was previously enabled, revoked tokens don't become active again. + When you [disable a user account](how-to-manage-user-accounts.md#manage-user-accounts-enable-disable) (which revokes refresh and access tokens), the revoked tokens don't become active if you enable the user account again. + When you create a new user pool client using the AWS Management Console, the AWS CLI, or the AWS API, token revocation is enabled by default. ## Enable token revocation Before you can revoke a token for an existing user pool client, you must enable token revocation. You can enable token revocation for existing user pool clients using the AWS CLI or the AWS API. To do this, call the `aws cognito-idp describe-user-pool-client` CLI command or the `DescribeUserPoolClient` API operation to retrieve the current settings from your app client. Then call the `aws cognito-idp update-user-pool-client` CLI command or the `UpdateUserPoolClient` API operation. Include the current settings from your app client and set the `EnableTokenRevocation` parameter to `true`. To create or modify an app client with token revocation enabled with the Amazon Cognito API or with an AWS SDK, include the following parameter in your [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API request. ``` "EnableTokenRevocation": true ``` To configure token revocation in the Amazon Cognito console, select an app client from the **App clients** menu in your user pool. Select the **Edit** button in **App client information** and enable or disable token revocation under **Advanced configuration**. ## Revoke a token You can revoke a refresh token using a [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API request, for example with the `[aws cognito-idp revoke-token](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/revoke-token.html)` CLI command. You can also revoke tokens using the [Revoke endpoint](revocation-endpoint.md). This endpoint is available after you add a domain to your user pool. You can use the revocation endpoint on either an Amazon Cognito hosted domain or your own custom domain. The following is the body of an example `RevokeToken` API request. ``` { "ClientId": "1example23456789", "ClientSecret": "abcdef123456789ghijklexample", "Token": "eyJjdHkiOiJKV1QiEXAMPLE" } ``` The following is an example cURL request to the `/oauth2/revoke` endpoint of a user pool with a custom domain. ``` curl --location 'auth.mydomain.com/oauth2/revoke' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic Base64Encode(client_id:client_secret)' \ --data-urlencode 'token=abcdef123456789ghijklexample' \ --data-urlencode 'client_id=1example23456789' ``` The `RevokeToken` operation and the `/oauth2/revoke` endpoint require no additional authorization unless your app client has a client secret. # Verifying JSON web tokens JSON web tokens (JWTs) can be decoded, read, and modified easily. A modified access token creates a risk of privilege escalation. A modified ID token creates a risk of impersonation. Your application trusts your user pool as a token issuer, but what if a user intercepts the token in transit? You must ensure that your application is receiving the same token that Amazon Cognito issued. Amazon Cognito issues tokens that use some of the integrity and confidentiality features of the OpenID Connect (OIDC) specification. User pool tokens indicate validity with objects like the expiration time, issuer, and digital signature. The signature, the third and final segment of the `.`-delimited JWT, is the key component of token validation. A malicious user can modify a token, but if your application retrieves the public key and compares the signature, it won't match. Any application that processes JWTs from OIDC authentication must perform this verification operation with each sign-in. On this page, we make some general and specific recommendations for verification of JWTs. Application development spans a variety of programming languages and platforms. Because Amazon Cognito implements OIDC sufficiently close to the public specification, any reputable JWT library in your developer environment of choice can handle your verification requirements. These steps describe verifying a user pool JSON Web Token (JWT). **Topics** + [Prerequisites](#amazon-cognito-user-pools-using-tokens-prerequisites) + [Validate tokens with aws-jwt-verify](#amazon-cognito-user-pools-using-tokens-aws-jwt-verify) + [Understanding and inspecting tokens](#amazon-cognito-user-pools-using-tokens-manually-inspect) ## Prerequisites Your library, SDK, or software framework might already handle the tasks in this section. AWS SDKs provide tools for Amazon Cognito user pool token handling and management in your app. AWS Amplify includes functions to retrieve and refresh Amazon Cognito tokens. For more information, see the following pages. + [Integrating Amazon Cognito authentication and authorization with web and mobile apps](cognito-integrate-apps.md) + [Code examples for Amazon Cognito Identity Provider using AWS SDKs](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html) + [Advanced workflows](https://docs.amplify.aws/lib/auth/advanced/q/platform/js/#retrieve-jwt-tokens) in the *Amplify Dev Center* Many libraries are available for decoding and verifying a JSON Web Token (JWT). If you want to manually process tokens for server-side API processing, or if you are using other programming languages, these libraries can help. See the [OpenID foundation list of libraries for working with JWT tokens](http://openid.net/developers/jwt/). ## Validate tokens with aws-jwt-verify In a Node.js app, AWS recommends the [aws-jwt-verify library](https://github.com/awslabs/aws-jwt-verify) to validate the parameters in the token that your user passes to your app. With `aws-jwt-verify`, you can populate a `CognitoJwtVerifier` with the claim values that you want to verify for one or more user pools. Some of the values that it can check include the following. + That access or ID tokens aren't malformed or expired, and have a valid signature. + That access tokens came from the [correct user pools and app clients](https://github.com/awslabs/aws-jwt-verify#verifying-jwts-from-amazon-cognito). + That access token claims contain the [correct OAuth 2.0 scopes](https://github.com/awslabs/aws-jwt-verify#checking-scope). + That the keys that signed your access and ID tokens [match a signing key `kid` from the *JWKS URI* of your user pools](https://github.com/awslabs/aws-jwt-verify#the-jwks-cache). The JWKS URI contains public information about the private key that signed your user's token. You can find the JWKS URI for your user pool at `https://cognito-idp..amazonaws.com//.well-known/jwks.json`. For more information and example code that you can use in a Node.js app or a AWS Lambda authorizer, see [https://github.com/awslabs/aws-jwt-verify](https://github.com/awslabs/aws-jwt-verify) on GitHub. ## Understanding and inspecting tokens Before you integrate token inspection with your app, consider how Amazon Cognito assembles JWTs. Retrieve example tokens from your user pool. Decode and examine them in detail to understand their characteristics, and determine what you want to verify and when. For example, you might want to examine group membership in one scenario, and scopes in another. The following sections describe a process to manually inspect Amazon Cognito JWTs as you prepare your app. ### Confirm the structure of the JWT A JSON Web Token (JWT) includes three sections with a `.` (dot) delimiter between them. **Header** The key ID, `kid`, and the RSA algorithm, `alg`, that Amazon Cognito used to sign the token. Amazon Cognito signs tokens with an `alg` of `RS256`. The `kid` is a truncated reference to a 2048-bit RSA private signing key held by your user pool. **Payload** Token claims. In an ID token, the claims include user attributes and information about the user pool, `iss`, and app client, `aud`. In an access token, the payload includes scopes, group membership, your user pool as `iss`, and your app client as `client_id`. **Signature** The signature isn't decodable base64url like the header and payload. It's an RSA256 identifier derived from a signing key and parameters that you can observe at your JWKS URI. The header and payload are base64url-encoded JSON. You can identify them by the opening characters `eyJ` that decode to the starting character `{`. If your user presents a base64url-encoded JWT to your app and it's not in the format `[JSON Header].[JSON Payload].[Signature]`, it's not a valid Amazon Cognito token and you can discard it. The following example application verifies user pool tokens with `aws-jwt-verify`. ``` // cognito-verify.js // Usage example: node cognito-verify.js eyJra789ghiEXAMPLE const { CognitoJwtVerifier } = require('aws-jwt-verify'); // Replace with your Amazon Cognito user pool ID const userPoolId = 'us-west-2_EXAMPLE'; async function verifyJWT(token) { try { const verifier = CognitoJwtVerifier.create({ userPoolId, tokenUse: 'access', // or 'id' for ID tokens clientId: '1example23456789', // Optional, only if you need to verify the token audience }); const payload = await verifier.verify(token); console.log('Decoded JWT:', payload); } catch (err) { console.error('Error verifying JWT:', err); } } // Example usage if (process.argv.length < 3) { console.error('Please provide a JWT token as an argument.'); process.exit(1); } const MyToken = process.argv[2]; verifyJWT(MyToken); ``` ### Validate the JWT The JWT signature is a hashed combination of the header and the payload. Amazon Cognito generates two pairs of RSA cryptographic keys for each user pool. One private key signs access tokens, and the other signs ID tokens. **To verify the signature of a JWT token** 1. Decode the ID token. The OpenID Foundation also [maintains a list of libraries for working with JWT tokens](http://openid.net/developers/jwt/). You can also use AWS Lambda to decode user pool JWTs. For more information, see [Decode and verify Amazon Cognito JWT tokens using AWS Lambda](https://github.com/awslabs/aws-support-tools/tree/master/Cognito/decode-verify-jwt). 1. Compare the local key ID (`kid`) to the public `kid`. 1. Download and store the corresponding public JSON Web Key (JWK) for your user pool. It is available as part of a JSON Web Key Set (JWKS). You can locate it by constructing the following `jwks_uri` URI for your environment: ``` https://cognito-idp..amazonaws.com//.well-known/jwks.json ``` For more information on JWK and JWK sets, see [JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517). **Note** Amazon Cognito might rotate signing keys in your user pool. As a best practice, cache public keys in your app, using the `kid` as a cache key, and refresh the cache periodically. Compare the `kid` in the tokens that your app receives to your cache. If you receive a token with the correct issuer but a different `kid`, Amazon Cognito might have rotated the signing key. Refresh the cache from your user pool `jwks_uri` endpoint. This is a sample `jwks.json` file: ``` { "keys": [{ "kid": "1234example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "1234567890", "use": "sig" }, { "kid": "5678example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "987654321", "use": "sig" }] } ``` **Key ID (`kid`)** The `kid` is a hint that indicates which key was used to secure the JSON Web Signature (JWS) of the token. **Algorithm (`alg`)** The `alg` header parameter represents the cryptographic algorithm that is used to secure the ID token. User pools use an RS256 cryptographic algorithm, which is an RSA signature with SHA-256. For more information on RSA, see [RSA cryptography](https://tools.ietf.org/html/rfc3447). **Key type (`kty`)** The `kty` parameter identifies the cryptographic algorithm family that is used with the key, such as "RSA" in this example. **RSA exponent (`e`)** The `e` parameter contains the exponent value for the RSA public key. It is represented as a Base64urlUInt-encoded value. **RSA modulus (`n`)** The `n` parameter contains the modulus value for the RSA public key. It is represented as a Base64urlUInt-encoded value. **Use (`use`)** The `use` parameter describes the intended use of the public key. For this example, the `use` value `sig` represents signature. 1. Search the public JSON Web Key for a `kid` that matches the `kid` of your JWT. ### Verify the claims **To verify JWT claims** 1. By one of the following methods, verify that the token hasn't expired. 1. Decode the token and compare the `exp` claim to the current time. 1. If your access token includes an `aws.cognito.signin.user.admin` claim, send a request to an API like [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html). API requests that you [authorize with an access token](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html#user-pool-apis-auth-unauth) return an error if your token has expired. 1. Present your access token in a request to the [userInfo endpoint](userinfo-endpoint.md). Your request returns an error if your token has expired. 1. The `aud` claim in an ID token and the `client_id` claim in an access token should match the app client ID that was created in the Amazon Cognito user pool. 1. The issuer (`iss`) claim should match your user pool. For example, a user pool created in the `us-east-1` Region will have the following `iss` value: `https://cognito-idp.us-east-1.amazonaws.com/`. 1. Check the `token_use` claim. + If you are only accepting the access token in your web API operations, its value must be `access`. + If you are only using the ID token, its value must be `id`. + If you are using both ID and access tokens, the `token_use` claim must be either `id` or `access`. You can now trust the claims inside the token. # Managing user pool token expiration and caching Your app must successfully complete one of the following requests each time you want to get a new JSON Web Token (JWT). + Request a client credentials or authorization code [grant](https://www.rfc-editor.org/rfc/rfc6749#section-1.3) from the [Token endpoint](token-endpoint.md). + Request an implicit grant from your managed login pages. + Authenticate a local user in an Amazon Cognito API request like [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). You can configure your user pool to set tokens to expire in minutes, hours, or days. To ensure the performance and availability of your app, use Amazon Cognito tokens for about 75% of the token lifetime, and only then retrieve new tokens. A cache solution that you build for your app keeps tokens available, and prevents the rejection of requests by Amazon Cognito when your request rate is too high. A client-side app must store tokens in a memory cache. A server-side app can add an encrypted cache mechanism to store tokens. When your user pool generates a high volume of user or machine-to-machine activity, you might encounter the limits that Amazon Cognito sets on the number of requests for tokens that you can make. To reduce the number of requests you make to Amazon Cognito endpoints, you can either securely store and reuse authentication data, or implement exponential backoff and retries. Authentication data comes from two classes of endpoints. Amazon Cognito [OAuth 2.0 endpoints](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html) include the token endpoint, which services client credentials and managed login authorization code requests. [Service endpoints](https://docs.aws.amazon.com/general/latest/gr/cognito_identity.html#cognito_identity_your_user_pools_region) answer user pools API requests like `InitiateAuth` and `RespondToAuthChallenge`. Each type of request has its own limit. For more information about limits, see [Quotas in Amazon Cognito](quotas.md). ## Caching machine-to-machine access tokens with Amazon API Gateway With API Gateway token caching, your app can scale in response to events larger than the default request rate quota of Amazon Cognito OAuth endpoints. ![\[A diagram of an API Gateway maintaining a cache of access tokens for M2M. The API proxy processes the token request and returns a cached token if one is already valid.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/user-pools-m2m-caching.png) You can cache the access tokens so that your app only requests a new access token if a cached token is expired. Otherwise, your caching endpoint returns a token from the cache. This prevents an additional call to an Amazon Cognito API endpoint. When you use Amazon API Gateway as a proxy to the [Token endpoint](token-endpoint.md), your API responds to the majority of requests that would otherwise contribute to your request quota, avoiding unsuccessful requests as a result of rate limiting. The following API Gateway-based solution offers a low-latency, low-code/no-code implementation of token caching. API Gateway APIs are encrypted in transit, and optionally at rest. An API Gateway cache is ideal for the OAuth 2.0 [client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4), a frequently high-volume grant type that produces access tokens to authorize machine-to-machine and microservice sessions. In an event like a traffic surge that causes your microservices to horizontally scale, you can end up with many systems using the same client credentials at a volume that exceeds the AWS request-rate limit of your user pool or app client. To preserve app availability and low latency, a caching solution is best practice in such scenarios. In this solution, you define a cache in your API to store a separate access token for each combination of OAuth scopes and app client that you want to request in your app. When your app makes a request that matches the cache key, your API responds with an access token that Amazon Cognito issued to the first request that matched the cache key. When your cache key duration expires, your API forwards the request to your token endpoint and caches a new access token. **Note** Your cache key duration must be shorter than the access token duration of your app client. The cache key is a combination of the OAuth scopes that you request in the `scope` parameter in the request body and the `Authorization` header in the request. The `Authorization` header contains your app client ID and client secret. You don't need to implement additional logic in your app to implement this solution. You must only update your configuration to change the path to your user pool token endpoint. You can also implement token caching with [ElastiCache (Redis OSS)](https://docs.aws.amazon.com/elasticache/index.html). For fine-grained control with AWS Identity and Access Management (IAM) policies, consider an [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/authentication-and-access-control.html#authentication) cache. **Note** Caching in API Gateway is subject to additional cost. [See pricing for more details.](https://aws.amazon.com/api-gateway/pricing) **To set up a caching proxy with API Gateway** 1. Open the [API Gateway console](https://console.aws.amazon.com/apigateway/main/apis) and create a REST API. 1. In **Resources**, create a POST method. 1. Choose the HTTP **Integration type**. 1. Select **Use HTTP proxy integration**. 1. Enter an **Endpoint URL** of `https:///oauth2/token`. 1. In **Resources**, configure the cache key. 1. Edit the **Method request** of your POST method. **Note** This method request validation is for use with `client_secret_basic` authorization in token requests, where the client secret is encoded in the `Authorization` request header. For validation of the JSON request body in `client_secret_post` authorization, create instead a [data model](https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings-models.html) that requires that [client\$1secret](token-endpoint.md#post-token-request-parameters-in-body) be present. In this model, your **Request validator** should **Validate body, query string parameters, and headers**. 1. Configure the method **Request validator** to **Validate query string parameters and headers**. For more information about request validation, see [Request validation](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html) in the *Amazon API Gateway Developer Guide*. 1. Set your `scope` parameter and `Authorization` header as your caching key. 1. Add a query string to **URL query string parameters**. Enter a query string **Name** of `scope` and select **Required** and **Caching**. 1. Add a header to **HTTP request headers**. Enter a request header **Name** of `Authorization` and select **Required** and **Caching**. 1. In **Stages**, configure caching. 1. Choose the stage that you want to modify and choose **Edit** from **Stage Details**. 1. Under **Additional settings**, **Cache settings**, turn on the **Provision API cache** option. 1. Choose a **Cache capacity**. Higher cache capacity improves performance but comes at additional cost. 1. Clear the **Require authorization** check box. Select **Continue**. 1. API Gateway only applies cache policies to GET methods from the stage level. You must apply a cache policy override to your POST method. Expand the stage you configured and select the `POST` method. To create cache settings for the method, choose **Create override**. 1. Activate the **Enable method cache** option. 1. Enter a ****Cache time-to-live (TTL)**** of 3600 seconds. Choose **Save**. 1. In **Stages**, note the **Invoke URL**. 1. Update your app to POST token requests to the **Invoke URL** of your API instead of the `/oauth2/token` endpoint of your user pool.