Step 3: Exchange authorization code for access and refresh tokens
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 resource owners are authenticated and granted access, they can exchange the authorization code for an access and a refresh token. Each token is associated with a single user (also called a subscriber) and a single application that wants to access protected resources in IBM Connections Cloud™.

Exchange authorization code for access and refresh tokens

During the API call, both a short-lived access token and a long-lived refresh token are generated. The access token expires after two hours. However, you can use the refresh token to obtain a new access token. The refresh token is a long-lived token that can remain valid up to 90 days, depending on your expiry configuration during registration.

API details

If you want to exchange the authorization code for the tokens via the API, you can make an HTTP call to following URI:

<app_server>/manage/oauth2/token


The following parameters are required:

Table 1. Input parameters
Parameter
Description
code
The authorization code returned by the OAuth 2.0 web server. The authorization code is used to get the access and refresh tokens. The maximum number of characters is 256.
grant_type
Set the value to authorization_code.
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.
callback_uri
The URI to redirect the user to after approval. The value must match the value in the Callback URL field when registering the company application.


Connections Cloud supports the following ways to send 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 callback_uri="<callback_uri>", client_secret="<client_secret>", client_id="<client_id>", grant_type="authorization_code", code="<authorization_code>"

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 with the request.
BAD REQUEST (400): oauth_unsupported_parameters: <parameter_list>
Unsupported parameters were passed with the request.
BAD REQUEST (400): oauth_invalid_parameters: <parameter_list>
Invalid parameters were passed with the request.
BAD REQUEST (400): oauth_unsupported_grant_type
The grant_type parameter that was passed with the request is not supported by Connections Cloud.
UNAUTHORIZED (401): oauth_missing_clientsecret
The client_secret parameter is either missing or has a null or empty value in the request.
UNAUTHORIZED (401): oauth_missing_callbackurl
The callback_uri parameter is either missing or has a null or empty value in the request.
UNAUTHORIZED (401): oauth_invalid_clientid
The OAuth 2.0 credential is not present or was deleted in Connections Cloud.
UNAUTHORIZED (401): Callback URI sent with the request is not the same as the one registered for this Company App
The callback_uri parameter that was sent with the request is not the same as the value that is registered for the application.
UNAUTHORIZED (401): fail decrypt client secret
The client secret cannot be decrypted.
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_missing_authorizationcode
The authorization_code parameter is missing from the request.
UNAUTHORIZED (401): oauth_invalid_authorizationcode
The authorization_code parameter is not valid.
UNAUTHORIZED (401): oauth_authorization_code_expired
The authorization code has expired.
UNAUTHORIZED (401): oauth_access_token_expired
The access token has expired.
UNAUTHORIZED (401): refresh token encrypt failure
The refresh token cannot be encrypted.
UNAUTHORIZED (401): fail decrypt refresh token
The refresh token cannot be decrypted.
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 2: Obtain authorization code
Next topic: Step 4: Use the access token to allow API access