3.6 Revoking Tokens

The client application can programmatically revoke its token in the following scenarios:

When an end user logs out.
When an application is uninstalled.
To notify Identity Server that a previously obtained refresh token is no longer needed.

The refresh token received in earlier flows can be revoked by sending a request to the revocation endpoint of Identity Server.

IMPORTANT:Only the refresh tokens that are generated by Access Manager Version 4.4 or later can be revoked.

The URL to revoke is https://idpbaseurl.com/nidp/oauth/nam/revoke.

The request should contain the refresh token and client credentials in HTTP request parameters as mentioned in the following table:

Parameter	Required/Optional	Description
client_id	Required	The client application ID that is obtained at the time of the client application registration process.
client_secret	Optional	The client secret that is obtained at the time of the client application registration process. The client secret is optional for a native application, but mandatory for a web application.
Token	Required	refresh_token that is obtained during authorization grant, resource owner credentials, client credentials flow

Parameter

Required/Optional

Description

client_id

Required

The client application ID that is obtained at the time of the client application registration process.

client_secret

Optional

The client secret that is obtained at the time of the client application registration process.

The client secret is optional for a native application, but mandatory for a web application.

Token

Required

refresh_token that is obtained during authorization grant, resource owner credentials, client credentials flow

Response Values

Identity Server responds with the HTTP status code 200 OK if the token has been revoked successfully or if the client submitted an invalid token.
Identity Server returns the error code unsupported_token_type when the provided token is not a refresh token.
If Identity Server responds with the HTTP status code 503, the client must assume that the token still exists and may retry revoking the refresh token after a reasonable delay.

Revoking Token Issued to a Device

When Mobile Access SDK is not used for on-boarding and off-boarding devices, the token can be manually associated with a device. This can be done by providing additional parameter device_id while requesting for an access token. Such manually associated tokens can be revoked by using the revocation endpoint.

The URL to revoke tokens that are issued to a device is:

https://idpbaseurl.com/nidp/oauth/nam/revoke/<device_id>

HTTP Post

Content-Type: application/x-www-form-urlencoded (Optional)

Request Parameters

Parameter	Required	Description
userstore_name	Yes	Specify the name of the user store.
user_dn	Yes	Specify the user's dn to whom the token issued.

Response Values

HTTP 200 OK
{
"status": "Successfully revoked token(s) issued to this device."
}

Sample Request

A sample request and response, with line breaks for better readability.

HTTP/1.1 POST /nidp/oauth/nam/revoke/andriodtest_1401
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/41.0.2228.0 Safari/537.36
Host: www.idp.com:8443
'userstore_name=namsignboxuserstore
& user_dn=cn%3Dharry%2Co%3Dnovell'

A successful response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, no-transform
Content-Length: 0
Date: Tue, 03 Mar 2015 18:12:55 GMT
{
"status": "Successfully revoked token(s) issued to this device."
}
Error Response

When an invalid device id specified or device had not been associated with any token, returns HTTP 404 NOT FOUND with error response

{
"error": "invalid_request",
"error_description": "Invalid device ID or no tokens to revoke for this device."
}