Authentication credentials are required in order to use the SMS API, making it secure unauthorized use. These credentials are Access Tokens (Oauth 2.0) or API keys.

This article explain you how to create, modify, and use an Application ID and Secret, which are required to generate Access Tokens.

Besides the API Key authorization method, the SMS API uses the OAuth 2.0 authorization framework. The OAuth 2.0 specification is a versatile authorization framework that defines a number of grants (called "methods") that a client application can use to obtain an access token. This token represents a user's permission for the client to access their data and can be used to authenticate a request to an API endpoint.

Our SMS API employs the client credentials grant (described in section 4.4 of RFC 6749), which is suitable for server-to-server authentication that need to take place in the background without  a specific user’s permission required. Most of the time, these kinds of applications are called daemons or service accounts.

Steps to create and use a new Application

1. After logging in to your SMS.CX account, go to HTTP API > Access Tokens (Oauth 2.0)and click on the button New Application.

   Give your application a name (optionally), select expiration time for the access token (1 day, 1 week, never), and choose the scopes to which it will be granted access (e.g. if you select the scope sms and groups, the tokens generated by this application will be granted access to send sms, create, delete, get groups of contacts)

   Click the Create button.

   

2. The new Application has been created, and you need to copy the Application ID and Application Secret and use them to get an Access Token from the authorization endpoint.

   

   You can always delete an Application, revoke all Access Tokens or reset the Application Secret, if you believe they have been compromised. Also, from the Web Panel, you can edit the settings of any application. For example, you can modify the access token expiration date, add or remove scopes, transliteration of SMS text, enforce sender ID, automatically remove emojis from SMS, set a quiet hours interval, set callback URLs (webhooks) for delivery report, receiving SMS, receiving opt-outs, shortlink hits, and more.
   

Get a token

After obtaining the required authorization for your application (ID & secret), you can move on to getting access tokens for API. To obtain a token with the client credentials grant, make a POST request to the /oauth/token authorization endpoint:

Note: The header Authorization Basic should be followed by a Base64 encoded value of APPLICATION_ID:APPLICATION_SECRET

The Base64 value for 3fd97176bd7e36c0e8fbd22b4b1ab5d29540b49c:129e24048c46c3bcabed1f9f267aef73f5f8e1e4 is

M2ZkOTcxNzZiZDdlMzZjMGU4ZmJkMjJiNGIxYWI1ZDI5NTQwYjQ5YzoxMjllMjQwNDhjNDZjM2JjYWJlZDFmOWYyNjdhZWY3M2Y1ZjhlMWU0IA==

HTTP request

POST /oauth/token HTTP/1.1
Host: api.sms.cx
Authorization: Basic M2ZkOTcxNzZiZDdlMzZjMGU4ZmJ...
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Bash request

curl --request POST \
  --url https://api.sms.cx/oauth/token \
  --header 'Authorization: Basic M2ZkOTcxNzZiZDdlMzZjMGU4ZmJ...' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --d 'grant_type=client_credentials'

Successful response

{
    "access_token": "a60e4455ec782fd54f37b8b9684dfa7a01c503c0",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "sms viber whatsapp multichannel conversations reports groups originators templates shortlinks attachments optouts account applications numbers"
}

Use a token

After you've obtained a token, use it to make requests to the nedeed resource. Once the access token expires, repeat the request to the /oauth/token endpoint to obtain a new one.

HTTP request

GET /groups
Host: https://api.sms.cx
Authorization: Bearer a60e4455ec782fd54f37b8...

Bash request

curl --request GET \
  --url https://api.sms.cx/groups \
  --header 'Authorization: Bearer a60e4455ec7...'

Security recommendations

• You shouldn't keep your Application ID and Application Secret right in your code. There are a lot of good reasons to keep them as environment variables.
  
• You can create as many Applications as you want, and from a security point of view, it is best to use more than one.
  
• Create a list of allowed IP addresses from the SMS.CX Dashboard to limit the use of Applications to only that list. This stops unauthorized access in case your Access Tokens or Application ID & Secret have been stolen.