Step 5: Get a new access token after the access token has expired
Added by IBM contributorIBM | Edited by IBM contributorAlex Leiskau on February 20, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

After the original access token expires, resource owners can use their refresh tokens to get a new access token. Using the new access token, they can access the protected resources on IBM Connections Cloud™ from the application.
Note: Each access and refresh token is associated with a single user (also called a subscriber) and a single application that accesses protected resources in IBM Connections Cloud.


Get a refresh token after the access token has expired

When users invoke an API with an expired access token, the error code 401 with an oauth_access_token_expired error message is returned. After receiving the error message, users can use the refresh token to get a new access token.

API details

If you want to get a new access token using the long-lived resource token, you can make an HTTP GET call to following URI:

<app_server>/manage/oauth2/token


The following parameters are required:

Table 1. Input parameters
Parameter
Description
grant_type
Set the value to refresh_token.
client_id
The client ID of your application. The client ID is provided at the time the application is registered.
client_secret
The client secret of your application. The client secret is provided at the time the application is registered. The maximum number of characters is 256.
refresh_token
A long-lived refresh token that can be used to obtain a new access token when the access token expires. The maximum number of characters is 256.

Note: The value of the refresh token is confidential and should be protected.


Connections Cloud supports the following ways to send these parameters:
  • Authorization header of a GET or POST request. Use Authorization: OAuth.
  • Body of a POST request. Make sure that the content type is Content-Type: application/x-www-form-urlencoded.
  • URL query parameters in a GET request.

Example of passing parameters as HTTP header:

https://apps.lotuslive.com/manage/oauth2/token

Authorization: OAuth client_secret="<client_secret>", client_id="<client_id>", grant_type="refresh_token", refresh token="<refresh_token>"

If the request is successful, the following parameters are returned in the body of the response with an HTTP response code of 200:

Table 2. Returned parameters
Parameter
Description
access_token
The short-lived access token. The default life span of the token is two hours. The maximum number of characters is 256.
refresh_token
A long-lived refresh token that can be used to obtain a new access token when the access token expires. The maximum number of characters is 256.

Note: The value of the refresh token is confidential and should be protected.
issued_on
The details of when the access token was created.
expires_in
The amount of time in milliseconds that the access token is valid.
token_type
The default value is Bearer.


Response codes and messages

Successful requests return a 200 response code. If your request is unsuccessful, refer to the following error codes and explanations:

BAD REQUEST (400): oauth_absent_parameters: <parameter_list>
The parameter_list parameters must be included in the request.
BAD REQUEST (400): oauth_duplicated_parameters: <parameter_list>
Duplicate parameters were passed in the request.
BAD REQUEST (400): oauth_unsupported_parameters: <parameter_list>
Unsupported parameters were passed in the request.
BAD REQUEST (400): oauth_invalid_parameters <parameter_list>
Invalid parameters were passed in the request.
UNAUTHORIZED (401): oauth_invalid_accesstoken
The access_token parameter is not valid.
UNAUTHORIZED (401): oauth_access_token_expired
The access token has expired.
UNAUTHORIZED (401): Service Component not found
The application associated with the credentials that were passed with the request cannot be found in Connections Cloud.
UNAUTHORIZED (401): oauth_consumer_missing_subscription
The user is not subscribed to this application.
FORBIDDEN (403):
OAuth 2.0 is not supported at this time. Contact your administrator.
INTERNAL SERVER ERROR (500): oauth_request_failed
The OAuth flow failed. Try again or contact the administrator.
Parent topic: OAuth 2.0 APIs for web server flow
Previous topic: Step 4: Use the access token to allow API access