2.5 Managing Tokens

2.5.1 Using Refresh Token

The access token has shorter lifetime. The refresh tokens have longer life time. Hence, to use access token for a longer duration you can use the refresh token. When the original access token is expired or going to expire, you can send a request with the refresh token to get a fresh access token. The refresh token is useful in a scenario where an application does not require frequent usage of authentication from user.

Identity Server issues refresh token for authorization code grant and resource owner grant.

NOTE:You can request for refresh token if the administrator has enabled the use of refresh token and if you have registered the application with token type as refresh token. For more information about registering the application, see Section 2.2, Registering the OAuth Client Application.

Requesting Access Token Using Refresh Token

The refresh token request should be sent to the Token Endpoint. The client application makes an HTTPS POST request to the /token endpoint for getting a fresh access token by using the refresh token.

Sample CURL request

curl --request POST \ 
--url https://<idphost:port>/nidp/oauth/nam/token \ 
--header 'content-type: application/x-www-form-urlencoded' \ 
--data 'grant_type=refresh_token&client_id=4e4ae330-1215-4fc8-9aa7-79df8325451c&client_secret=Rxl5pvgL80DBzbIcLPVnH17FehZA8L&refresh_token=eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1.....'

Request Parameter



Value should be "refresh_token'"


Client ID of the registered client


Client Secret of the registered client. It is optional for native application, for web application secret is mandatory.


refresh_token that is obtained during authorization code, resource owner credentials flow

For information about other request parameters, see Section 4.4, Token Endpoint.

Receiving Access Token

Sample token response

{"access_token": "eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.....","token_type" : "bearer","expires_in" : 3599, "scope" : "profile email"}

Response Parameter



The type of the token. Authorization server currently supports only Bearer type


Fresh access token that can be used to invoke resource server APIs


Optionally re-issues a refresh token if configured in client application


The remaining lifetime of the access token.


The granted scopes to the client.

NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains "error" and "error_description".

2.5.2 Revoking Tokens

Prerequisite: Inform the Access Manager administrator to enable token revocation in the OAuth global settings of Identity Server.

The client application can revoke the refresh token in the following scenarios:

  • The end-user logs out

  • The application is uninstalled

  • To notify the Identity Server that a previously obtained refresh token is no longer required.

The refresh token received in earlier flows can be revoked by sending an HTTPS Post request to the revocation endpoint, /revoke of Identity Server.

NOTE:Only the refresh tokens that are in JWT format can be revoked. Therefore, You can revoke only the refresh tokens that are issued from Access Manager 4.4 or later versions.

Application Request to Revoke Refresh Token

Sample request

curl --request POST \ 
--url https://<idphost:port>/nidp/oauth/nam/revoke\ 
--header 'content-type: application/x-www-form-urlencoded' \ 
--data 'client_id=bb775b12-bbd4-423b-83d9-647aeb98608d&client_secret=bBbE-4mNO_kWWAnEeOL1CLTyuPhNLhHkTThArEckyr&token=eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyOD'

Request Parameter



Client ID of the registered client


Client Secret of the registered client. It is optional for native application, for web application secret is mandatory.


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

Application Receives Response for Revoking Refresh Token

  • The Identity Server responds with HTTP status code 200 OK if the token has been revoked successfully or if the client submitted an invalid token.

  • The error code unsupported_token_type is returned by the Identity Server when the given token is not a refresh token.

  • If the Identity Server responds with HTTP status code 503, the client must assume the token still exists and may retry revoking the refresh token after a reasonable delay.

2.5.3 Revoking Token Issued to a Device

You can ask the Access Manager administrator to revoke refresh tokens that are issued to a device. This feature is helpful in following scenarios:

  • If the device is stolen or user lost the device

  • Token is given to user for multiple devices and one device is compromised.

  • User revokes by revoking the consent.

    When consent is removed, user is required to grant permission again to use the token.

The token can be manually associated with a device by providing additional parameter "device_id" while requesting for access token. Such manually associated tokens can be revoked using the revocation endpoint.

Application Requests for Revoke Token issued to a Device

The client application makes HTTPS POST request to /revoke endpoint with device_id as path parameter.

Sample CURL request

curl --request POST \ 
--url https://<idphost:port>/nidp/oauth/nam/revoke/<device_id>\ 
--header 'content-type: application/x-www-form-urlencoded' \ 
--data 'userstore_name=namsignboxuserstore&user_dn=cn%3Dharry%2Co%3Dnovell'

The request parameters that are used






Specify the name of the user store



Specify the user's dn to whom the token issued.

Application Receives Response

Sample successful response

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

NOTE:If validation errors are occurred, HTTP Status 4xx returned with the JSON response contains "error" and "error_description".

2.5.4 Validating a JWT Token

The tokens are validated based on the configuration of the resource server that is managed through Access Manager Administration Console. To validate access tokens, you require to understand the encryption method used for encrypting the access tokens.

By default token encryption is done by using Access Manager keys. To encrypt access token using resource server keys share the encryption keys details in JWKS format (JSON Web Key Set) or JWKS URI to Access Manager Administrator for creating custom resource server using either REST API or Administration Console.

Refresh tokens are always encrypted by using Access Manager Encryption keys.

Validating Tokens Encrypted Using the Access Manager keys

To validate access tokens and refresh token that are signed and encrypted by using Access Manager encrypted keys, send a request to TokenIntrospect endpoint, /introspect.

Sample request

The request should contain the token in the Authorization header as follows:

Authorization: Bearer access_token

curl --request POST \

--url https://<idphost:port>/nidp/oauth/v1/nam/introspect \
--header 'content-type: application/x-www-form-urlencoded;Authorization: Bearer eyJraWQiOiI0MjgzNzQyNDYxMjE5OTM1ODU5OTYyODYwNzYyODAzMzEyNjI1MjUzMDQyMTk0NDMiLCJ0.... \'
--data 'token=eyJhbGciOiJBMT........._.xvpQmbtb-hzR6TAs3dOm7A

Sample response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 296
Date: Thu, 19 Mar 2015 15:47:25 GMT
"active": true,"exp": 1536731362,"nbf": 1536727762,"iat": 1536727762,"scope": [],"token_type": "bearer","jti": "9b7d2252-cb1d-4e41-9155-97fe2f3dc85a","iss": "https://<Identity Server hostname>/nidp/oauth/nam","aud": "21ae0625-f319-4b24-bf52-b2fc7e2a866a","client_id": "21ae0625-f319-4b24-bf52-b2fc7e2a866a"

The response will have the following parameters




A boolean value indicating whether the mentioned token in the introspection request is currently active.


The client identifier for the OAuth 2.0 client that requested this token.


The timestamp in seconds indicating when the token will expire.

NOTE:If validation errors are occurred, HTTP Status 400 returned with the JSON response contains "error" and "error_description".

Validating Tokens Encrypted Using Resource Server Keys

When the access token is encrypted using the resource server keys, the resource server can validate the token without contacting Access Manager's token verification endpoint.

A resource server can validate using the following sample code written in JAVA:

Sample Java code to validate a token

//Step1: decrypt the JWT Token (JWE Standard)
String jwtAccessToken =
JsonWebEncryption jwe = new JsonWebEncryption();
JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jwks);
List<JsonWebKey> jsonWebKeys = jsonWebKeySet.getJsonWebKeys();
JsonWebKey jsonWebkey = jsonWebKeys.stream().filter( p ->p.getKeyId().equalsIgnoreCase(jwe.getKeyIdHeaderValue())).findFirst().orElse(jsonWebKeys.get(0));
if(jsonWebkey instanceof RsaJsonWebKey){RsaJsonWebKey rsa = (RsaJsonWebKey) jsonWebkey;
}String decryptedToken = jwe.getPlaintextString();
//Step 2: Verify the JWT Signature (JWS Standard)JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jwks);JsonWebKey jsonWebkey = jsonWebKeySet.getJsonWebKeys().get(0);JsonWebSignature jws = new JsonWebSignature();
if(true == jws.verifySignature()){System.out.println("Signature is valid.");String payload = jws.getPayload();

For detailed sample code and tool for validating the JWT access token, refer JWT Validation tool and Readme under Additional Resources of Access Manager documentation page.

Validating Unencrypted Tokens

When the token is not encrypted, the resource server can validate the token signature. In the Java code, you can use the step 2 of the sample that is mentioned in the preceding section.