Using OAuth 2.

0 to Access Bulk SMS APIs

This document explains how SMS client applications should use OAuth 2.0 endpoints to implement
OAuth 2.0 authorization to access Bulk SMS APIs.OAuth 2.0 allows users to access send SMS endpoint
while keeping their usernames, passwords, and other information private. To begin, obtain OAuth 2.0
client credentials from your service agent. Then your client application can request an access token and a
refresh token from the Bulk SMS Authorization Server, extract the access token from the response, and
send the token to the Send SMS API to send SMSs.

OAuth 2.0 Login

This endpoint is used to retrieve the refresh and access tokens required to access the send SMS API.
Request URL

https://{oauth-provider-url}/api/login

Sample request headers

POST /api/login HTTP/1.1Content-Type: application/jsonAccept: */*X-API-VERSION: v1

Sample request body

{
"username": "abc@example.com",
"password": "abc@123"
}

Sample response body

{
"accessToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiO
iJhY2Nlc3NUb2tlbiIsImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awXj
QajibL9MhzE4XjXqwaQ-ypWSXYbsSptn6wHIHcROtbh5P34MTORpZh98yykBQ298Fkw",
"refreshToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUi
OiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2MjkzMDkxNDYsImlhdCI6MTYyOTIyMjc0Nn0.VUtAnwdSjsMesxs90
lw39GvYOLK8QY_cyHiFmYzYGtiX9AtCk1SmvWgn2-lh-5EgWJit6gRssHbeQvH-rqF5RA"
}

You can use the access token to access the send SMS API and the refresh token to renew the access
token when expired.
OAuth 2.0 Token Renew
This endpoint is used to renew the access token required to access the send SMS API, using the refresh
token provided at the login. The refresh token is sent in the header (Authorization: Bearer [refresh token]).
Request URL
https://{oauth-provider-url}/api/token/accessToken

Sample request headers

GET /api/token/accessToken HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cG
UiOiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0
lIbV8BT1C8eXEgYVUNn_u75uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_JSa0N9fSUybo-AMg

Sample response body

{
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUi
OiJhY2Nlc3NUb2tlbiIsImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awX
jQajibL9MhzE4XjXqwaQ-ypWSXYbsSptn6wHIHcROtbh5P34MTORpZh98yykBQ298Fkw"
}

If you receive HTTP error code 401 (Unauthorized) for the token renew API request, you should call the
login API to retrieve a fresh set of access and refresh tokens.

OAuth 2.0 Send SMS

This endpoint is used to send SMS, using the access token. The access token is sent in the header
(Authorization: Bearer [access token]).
Request URL

https://{oauth-provider-url}/api/sendsms

Sample request headers

POST /api/sendsms HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cG
UiOiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0
lIbV8BT1C8eXEgYVUNn_u75uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_JSa0N9fSUybo-AMg

Sample request body

{
"campaignName": "Test campaign",
"mask": "Test",
"numbers": "94780000000",
"content": "Test message"
}

Sample response body

{
"serverRef": 32225
}

If you receive HTTP error code 401 (Unauthorized) for the send SMS API request, you should call the
token renew API to retrieve a fresh access token.