Using the refresh token - Amazon Cognito
Refreshing tokensRevoking refresh tokens

Using the refresh token

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.

The Mobile SDK for iOS, Mobile SDK for Android, Amplify for iOS, Android, and Flutter automatically refresh your ID and access tokens if a valid (unexpired) refresh token is present. The ID and access tokens have a minimum remaining validity of 2 minutes. If the refresh token is expired, your app user must re-authenticate by signing in again to your user pool. If the minimum for the access token and ID token is set to 5 minutes, and you are using the SDK, the refresh token will be continually used to retrieve new access and ID tokens. You will see expected behavior with a minimum of 7 minutes instead of 5 minutes.

Your user's account itself doesn't expire, as long as the user has logged in at least once before the UnusedAccountValidityDays time limit for new accounts.

Getting new access and identity tokens with a refresh token

Use the API or hosted UI to initiate authentication for refresh tokens.

To use the refresh token to get new ID and access tokens with the user pools API, use the AdminInitiateAuth or InitiateAuth 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.

Note

To use the Amazon Cognito user pools API to refresh tokens for a hosted UI user, generate an InitiateAuth request.

You can also submit refresh tokens to the Token endpoint 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.

Revoking refresh tokens

You can revoke refresh tokens that belong to a user. For more information about revoking tokens, see Revoking tokens.

Note

Revoking the refresh token will revoke all ID and access tokens that Amazon Cognito issued from refresh requests with that token.

Users can sign out from all devices where they are currently signed in when you revoke all of the user's tokens using the GlobalSignOut and AdminUserGlobalSignOut API operations. 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 hosted UI 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 hosted UI users, redirect them to the Logout endpoint, where Amazon Cognito will clear 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 devices where they have signed in, continually refreshing their session. To sign your user out from a single device, revoke their refresh token. When your user wants to sign themself out from all authenticated sessions, generate a GlobalSignOut 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 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 Amazon Cognito user pools authenticated and unauthenticated API operations.