Using Clickatell Secure REST API
Overview
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. 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 of the simplest way to request a Secure authentication (Grid in this case).
- Step 1: Replace the example authentication token below with your token.
- Step 2: Replace the example mobile numbers below with your number, using the 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’
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
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.
Submit a Comment
Other Resources
Ask the Community
Visit Stack Overflow to join our community of developers and find the answer you need
Contact Support
Contact our support team and one of our agents will be in touch with you to answer any questions you have