Skip to content

Revoke tokens

OAuth2.0 supports token revocation to revoke any access granted by them. This token endpoint can revoke access tokens and refresh tokens.

Confidential clients such as web apps can keep the client credentials securely. Those clients need to prove their identity when they access the revocation endpoint to revoke access tokens.

Public clients such as SPAs, mobile apps can't store credentials securely. Those apps need to submit only their client ID to identify the apps during token revocation.

Note

  • Revoking a refresh token via the revocation endpoint will not revoke the respective access token.
  • Revoking an access token via the revocation endpoint will not revoke the respective refresh token.

Token revocation endpoint

https://api.asgardeo.io/t/{organization_name}/oauth2/revoke

Token revocation by confidential clients

When your application is a confidential client, it needs to identify itself to the token endpoint by submitting the client_id as well as the client_secret. You can use one of the following methods:

  • Use client_secret_post: The client_id and client_secret are both sent as body parameters in the POST message.
  • Use client_secret_basic: The client secret is sent as an authorization header in the request ('Authorization: Basic BASE64_ENCODE<client_id:client_secret>').

Apart from client authentication, the revocation request has some other parameters as well.

Request Parameter Description
token The token you want to revoke.
token_type_hint The type of token. If the token is an access token, the type should be access_token. For a refresh token, the type should be refresh_token.

Client secret post based authentication

In this method, the app can send the client_id and client_secret as body params in the revocation request.

The sample request is given below.

curl --location --request POST 'https://api.asgardeo.io/t/bifrost/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token={token}' \
--data-urlencode 'token_type_hint={token_type}' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}'
var settings = {
    "url": "https://api.asgardeo.io/t/{organization_name}/oauth2/revoke",
    "method": "POST",
    "timeout": 0,
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "data": {
        "token": "{token}",
        "token_type": "{token_type}",
        "client_id": "{client_id}",
        "client_secret": "{client_secret}"
    }
};

$.ajax(settings).done(function (response) {
    console.log(response);
});
var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
    'token': '{token}',
    'token_type_hint': '{token_type}',
    'client_id': '{client_id}',
    'client_secret': '{client_secret}',
});
var config = {
    method: 'post',
    url: 'https://api.asgardeo.io/t/{organization_name}/oauth2/revoke',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data : data
};

axios(config)
    .then(function (response) {
        console.log(JSON.stringify(response.data));
    })
    .catch(function (error) {
        console.log(error);
    });

Client secret basic authentication

In client secret basic authentication, the application has to do base64 encoding on the client ID and client secret and pass that as a basic authorization header in the revocation request.

The authorization header should look as follows:

Basic BASE46_ENCODING<your_client_id:your_client_secret>

Tip

To perform base64 encoding for the client ID and secret, you can use a tool, or you can run the below command.

echo -n '<your_client_id:your_client_secret>' | base64

Sample request

curl --location --request POST 'https://api.asgardeo.io/t/bifrost/oauth2/revoke' \
--header 'Authorization: Basic ejhSQjZ5c2REWmhlNFFPMHpKQVF6S2JpNlA0YTp6MEM3OXpsb3B4OGk3QnlPdzhLMTVBOWRwbFlh' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token_type_hint=access_token' \
--data-urlencode 'token=292896cf-5525-3551-b9e2-1787f1114924'

When the token is revoked, you will get a 200 OK response.

Token revocation by public clients

Since public clients cannot store credentials securely and they do not need to perform authentication when revoking a token. However, they need to submit their client ID.

Sample request

curl --location --request POST 'https://api.asgardeo.io/t/bifrost/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token={token}' \
--data-urlencode 'token_type_hint={token_type}' \
--data-urlencode 'client_id={client_id}'
var settings = {
    "url": "https://api.asgardeo.io/t/{organization_name}/oauth2/revoke",
    "method": "POST",
    "timeout": 0,
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "data": {
        "token": "{token}",
        "token_type": "{token_type}",
        "client_id": "{client_id}"
    }
};

$.ajax(settings).done(function (response) {
    console.log(response);
});
var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
    'token': '{token}',
    'token_type_hint': '{token_type}',
    'client_id': '{client_id}'
});
var config = {
    method: 'post',
    url: 'https://api.asgardeo.io/t/{organization_name}/oauth2/revoke',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data : data
};

axios(config)
    .then(function (response) {
        console.log(JSON.stringify(response.data));
    })
    .catch(function (error) {
        console.log(error);
    });

This token revocation request for public clients takes the following parameters:

Request Parameter Description
token The token (access token or refresh token) you want to inspect.
token_type_hint The type of the token. If the token is an access token, the type should be access_token. For a refresh token, the type should be refresh_token.
client_id The client ID of the application.

When the token is revoked, you will get a 200 OK response.

Note

You will always get a 200 OK response when you try to revoke an invalid token, expired, or already revoked. This helps to prevent any information leaks.