Using the Secure REST API

The Clickatell Secure REST API enables you to send Secure Pin or Grid-based 2FA requests through the Clickatell Secure service. It also allows you to check if the passed PIN code matches the specified API request ID, as well as the status of a Grid authentication.

The API provides simplified authentication through a single key and incorporates version control mechanisms to allow for future upgrades.

The Clickatell Secure REST API comes with the following features:

  • Supports JSON and XML data format.
  • Use of a single authentication token.
  • Specify the type of 2FA request (Secure Pin, Secure Grid or Secure GridPlus).
  • Specify the number of challenges for Secure Grid and Secure GridPlus, one to three (default is three).
  • Specify the authentication timeout length in minutes (default is five minutes).
  • Specify the maximum number of retries for Secure authentication attempts. After the last failed retry, the authentication will fail (default is one retry).
  • Specify the number of Grid icons per screen. Icons are displayed in two columns, so an even number between two and eight must be specified. We don’t recommend more than eight icons per screen (default is six icons per screen).
  • Specify the image categories for SecureGrid which serves as the end-user's visual password (no default).

 

Clickatell Secure setup

  • Step 1: Sign up for a Clickatell Secure account. Once you activate your account, you’ll receive free test credits to try out the Secure service.
  • Step 2: Complete the activation wizard and register your mobile number. This will enable you to configure additional 2FA login security to protect your account.
  • Step 3: From the Integrations menu, select Set up a new integration. You can name your integration. Upon completion, you will be issued an authentication key that you will need to operate Clickatell Secure.
  • Step 4: Once you have completed testing, you can select your preferred product plan to operate your authentication service.

Once you have your Clickatell Secure integration set up, you’ll need to integrate your newly created service into your project. Please note that for your integration, you will be required to make RESTful calls to the Clickatell Secure service API and pass valid JSON objects (or XML documents) with the relevant details. All calls must be made to https://api.clickatell.com/rest/auth.

Request your first Secure authentication

The following is an example for the simplest way to request a Secure authentication (Grid in this case).

curl -X POST \

-H "X-Version: 1" \

-H "Content-Type: application/JSON" \

-H "Accept: application/JSON" \

-H "Authorization: Bearer [Your Authorization Token]" \

-d '{"authType":"grid","to":"2799900001"}' \

https://api.clickatell.com/rest/auth

 

  • Step 1: Replace the example authentication token above with your token.
  • Step 2: Replace the example mobile numbers above with your number, using correct international format. This means:
    • The mobile number needs to start with the correct country code.
    • There must be no spaces or other non-numeric characters.
    • If the mobile number starts with zero, remove the zero before typing the rest of the number.
  • Step 3: Specify the authentication you want to request which can be either ‘Pin’, ‘Grid’ or 'GridPlus'

 

HTTP headers explained

Header

Description

Examples

Authorization

Required to authenticate your API 2FA requests. The authentication token for this header is displayed in your Secure account.

Authorization: Bearer wYd5_sMDBIeo0tb5X2f_yTQsPfLQbmcH9ClI5nlXaD5BW4G7B_K9fIPERG5fDo

X-Version

Specifies which version of the API to use.

X-Version:1

Content-Type

Used to indicate whether you are submitting data in JSON or XML format. Supports application/json and application/xml. There is currently no support for x-www-form-urlencoded.

Content-Type: application/json

Accept

Used to indicate if you want a JSON or XML response format. Defaults to JSON if not specified. If specified, the API expects application/json,application/xml or */*.

Accept: application/json

Authenticating

Authentication is done using an authentication token (generated within a Clickatell Secure account). This token needs to be passed along with every REST API call. The header used for this is explained in the section called ‘HTTP headers explained’, above.