The implementation of SCG (Syniverse Communication Gateway) API access policies now have the support of OAuth 2.0 as an option to manage SCG API access.
Syniverse SDC (Syniverse Developer Community) provides the UI to perform the SCG API access token expiration set up and re-generation of a new token. This allows to regenerate the access token and provides the option to set the token expiration time. This can be used to manually implement API access policies, for example: setting up a one-year expiration time. The user must be aware of the expiration time and re-generate the token in a timely manner.
As there are enterprises, where manual procedure downtimes are not an option, due to the intensive use of the communication platform, Syniverse provides OAuth 2.0 APIs to programmatically refresh/revoke the SCG access token in the consumer process side. These functionalities allow the implementation of access token expiration policies in enterprise applications. For example: setting an automated process that once-a-year revoke/refresh the current access token.
Token endpoint
This API is used to retrieve the current valid access token and related info using the user credentials. The credential required to call this API are the Customer Key and the Customer Secret that SDC provides in the Auth Keys section of the SDC application Details and Stats.
In this section you will find the Auth Keys:
The token API call requires to include a header with the Consumer Key and the Consumer Secret separated by colon encoded in base64. The header value, also must have a prefix "Basic".
Example: Given the credentials
Consumer Key: jKCJqiKb5X2wRftKg0pIbfjTAYwa
Consumer Secret: yrIjKGtRHoKXEVIUybtLylJNlPUa
We need to encode the string:
jKCJqiKb5X2wRftKg0pIbfjTAYwa:yrIjKGtRHoKXEVIUybtLylJNlPUa
into base64:
aktDSnFpS2I1WDJ3UmZ0S2cwcEliZmpUQVl3YTp5cklqS0d0UkhvS1hFVklVeWJ0THlsSk5sUFVh
With this credential string we can perform the API call using the header:
-H 'Authorization: Basic aktDSnFpS2I1WDJ3UmZ0S2cwcEliZmpUQVl3YTp5cklqS0d0UkhvS1hFVklVeWJ0THlsSk5sUFVh'
Payload: The API payload requires the below parameters
grant_type: this parameter must be set as "client_credentials"
validity_period: this parameter unit is in seconds and must be at least 300 seconds to allow the system time to synchronize and prevent expiration issues.
Payload format:
The API payload format is: x-www-form-urlencoded
The token API call in a curl format is:
curl -L -X POST 'https://api.syniverse.com/token' \
-H 'Authorization: Basic aktDSnFpS2I1WDJ3UmZ0S2cwcEliZmpUQVl3YTp5cklqS0d0UkhvS1hFVklVeWJ0THlsSk5sUFVh' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'validity_period=300'
When the above curl is executed, it returns the json:
{
"access_token": "111c95e4-e3eb-38e1-b19b-b8b1b9d2f108",
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 300
}
access_token: this field returns the current valid access token. When the access token is expired, the API returns the new access token (refresh).
scope: the access_token scope.
expires_in: this field returns the current remaining time for the access_token.
token_type: self-explanatory.
This access_token, can then be used to perform SCG API calls to send messages and/or any operation that require the SCG access token.
Revoke endpoint
This method is used when the enterprise decided to end the validity of the current access token.
To execute this API call, the same credentials are needed and in addition the access token to revoke as parameter.
The curl command to revoke the same access token is:
curl -L -X POST 'https://api.syniverse.com/revoke' \
-H 'Authorization: Basic aktDSnFpS2I1WDJ3UmZ0S2cwcEliZmpUQVl3YTp5cklqS0d0UkhvS1hFVklVeWJ0THlsSk5sUFVh' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token=111c95e4-e3eb-38e1-b19b-b8b1b9d2f108'
This API successful execution returns:
200 OK
After Revoking an access token
If an SCG API call is made using a revoked access token, the API call will return the below error message:
<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
<ams:code>900901</ams:code>
<ams:message>Invalid Credentials</ams:message>
<ams:description>Access failure for API: /scg-external-api/api/v1, version: v1 status: (900901) - Invalid Credentials. Make sure you have provided the correct security credentials</ams:description>
</ams:fault>
A token API call must be executed to get a new/valid access token and update the SCG API calls to start using the new access token.
0 Comments