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.
If you want to exchange the authorization code for the tokens via the API, you can make an HTTP call to following URI:
The following parameters are required:
Table 1. Input parameters
|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.|
SmartCloud for Social Business supports the following ways to send parameters:
Example of passing parameters as HTTP header:
Authorization: OAuth callback_uri="<callback_uri>", client_secret="<client_secret>", client_id="<client_id>", grant_type="authorization_code", code="<authorization_code>"
- 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.
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
|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 SmartCloud for Social Business.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 SmartCloud for Social Business.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 SmartCloud for Social Business.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