How do I revoke refresh tokens that Amazon Cognito issued?

Resolution

You can use APIs and endpoints to revoke refresh tokens that Amazon Cognito generated.

Note: You can revoke refresh tokens in real time so that these refresh tokens can't generate access tokens.

Prerequisites to revoke refresh tokens

Turn on token revocation for an app client to revoke the refresh tokens that the app client issued. The EnableTokenRevocation parameter is turned on by default when you create a new Amazon Cognito user pool client. Before you can revoke a token for an existing user pool client, turn on token revocation within the UpdateUserPoolClient API operation. Include the current settings from your app client and set the EnableTokenRevocation parameter to true.

When you turn on token revocation settings, the origin_jti and jti claims are added to the access and ID tokens:

• The jti claim provides a unique identifier for JSON Web Tokens (JWTs).
• The jti claim is used to prevent the JWTs from being replayed.
• The jti value is a case-sensitive string.
• When the REFRESH_TOKEN authentication flow is used to generate new access and ID tokens, the new access and ID tokens have the same origin_jti claim. The jti claims are different.

For more information, see Turn on token revocation and Understanding user pool JWTs.

Expected results of revoking refresh tokens

For information about what to expect when you revoke refresh tokens, including the effects, see Revoking tokens and RevokeToken.

Note: For more information about JWTs, see Verifying JSON web tokens.

Using the RevokeToken API call to revoke refresh tokens

To call the RevokeToken API, you must have the refresh token to that you want to revoke, the app client ID, and the client secret.

Note: You only need the client secret when the client ID has a secret.

Request syntax:

{ 
  "ClientId": "string", 
  "ClientSecret": "string", 
  "Token": "string" 
}

Example AWS Command Line Interface (AWS CLI) command:

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

aws cognito-idp revoke-token 
--token <value> 
--client-id <value> 
--client-secret <value>  

Note: Replace the token with your token information. Replace the client-id with your client ID. Replace the client-secret with your app client's secret.

Example curl command:

Note: Replace with your AWS Region. Replace with your token information. Replace with your client ID.

awscurl \ 
-v \ 
-X POST \ 
--service cognito-idp \ 
--region <region> \ 
-H 'X-Amz-Target: AWSCognitoIdentityProviderService.RevokeToken' \ 
-H 'Content-Type: application/x-amz-json-1.1' \ 
-d '{"ClientId": "<client-id>", "Token": "<refresh-token>"}' \ 
https://cognito-idp.<region>.amazonaws.com  

Using the revoke endpoint to revoke refresh tokens

The /oauth2/revoke endpoint is available after you add a domain to your user pool. After the endpoint revokes the tokens, you can't use the revoked tokens to access the APIs that Amazon Cognito tokens authenticate. For information about the /oauth2/revoke endpoint, including request parameters, see The token revocation endpoint.

Example 1: Revoke token with an app client with no app secret:

POST /oauth2/revoke HTTP/1.2 
    Host: https://mydomain.auth.<region>.amazoncognito.com 
    Accept: application/json 
    Content-Type: application/x-www-form-urlencoded 
    token=<refresh token>& 
    client_id=<client-id>  

Note: Replace with your Region. Replace with your refresh token information. Replace with your client ID.

Example 2: Revoke token with an app client with app secret:

POST /oauth2/revoke HTTP/1.2 
    Host: https://mydomain.auth.<region>.amazoncognito.com 
    Accept: application/json 
    Content-Type: application/x-www-form-urlencoded 
    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 
    token=<refresh token>  

To learn about setting up an authorization header, see How do I troubleshoot "Unable to verify secret hash for client" errors from my Amazon Cognito user pools API?

Endpoint errors

For more information about endpoint errors, see Revocation error response.