Request Secure Grid authentication

This command allows you to request a single Secure Grid authentication.

The server will respond with a unique identifier for each 2FA request (referred to as an API request ID). This API request ID can be used to track and monitor the status of your 2FA request.

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

Note that the REST API may respond with various HTTP status codes.

Secure Grid challenge flow

  • Step 1: Make an HTTP POST to have a Grid challenge sent to a mobile number. You can specify various optional parameters within your request. An API request ID is returned.
  • Step 2: Use the resulting request ID to check the status of the Grid authentication by making a GET call to the Secure REST API. You can make the call every five seconds for example to determine the status of an authentication.
  • Step 3: As a response (HTTP GET), you will receive a data packet with the status of the challenge (challengeSolved) set to either true or false, as well as a description of the status.

HTTP POST

Description

It makes a new multi-factor authentication (MFA) request. A message is sent with a challenge to the user (such as a PIN code or a grid of images).

API endpoint

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

Supported parameters

  • to [ Required – MSISDN ]
  • from [ Optional – For sending from a two-way number or specifying a custom sender ID ]
  • authType [ Required – Only accepts pin or grid ]
  • overrideExpireTime [ Optional – Defaults to 5 minutes ]
  • maximumRetries [ Optional – Defaults to 1 attempt ]
  • numberOfChallenges [ Optional - Defaults to 3 ]
  • numberOfImagesPerChallenge [ Optional – Default is 6 image icons ]
  • companyImageUrl [ Optional – Default is Clickatell’s logo ]

Returns

  • API Request ID (to reference the MFA)

Notes

  • Only one mobile number can be specified per HTTP request.
  • The from parameter represents the two-way number that you are sending from. This parameter is only required if you want to send messages using a two-way number (short code or long number).
  • The maximumRetries parameter indicates how many chances a user has to solve a Grid challenge.

JSON

Request

POST /rest/auth HTTP/1.1
HOST: api.clickatell.com
X-Version: 1
Content-Type: application/JSON
Authorization: Bearer [Your Authorization Token]
Accept: application/JSON
{"authType":"grid","to":"2799900001","overrideExpireTime":"10","maximumRetries":"2",
 "numberOfChallenges":"2","numberOfImagesPerChallenge":"8",
 "companyImageUrl":"http://www.yourwebsite.com/logo_image.jpg"}

Response

HTTP/1.1 202 Accepted
Content-Type: application/JSON

{
   "data":{
            "apiRequestId":"p49d6c09e1ff529ec7dacb225707cad2"
   }
}

Sample code

PHP

<?php
$to="";
$authType="grid";
$overrideExpireTime="10";
$maximumRetries="2";
$challenges="2";
$images="8";
$companyImageUrl="http://www.yourwebsite.com/logo_image.jpg";
$authToken="";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,            "https://api.clickatell.com/rest/auth");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST,           1);
curl_setopt($ch, CURLOPT_POSTFIELDS,     "{\"authType\":\"$authType\"
                                                ,\"to\":\"$to\"
                                                ,\"overrideExpireTime\":$overrideExpireTime
                                                ,\"maximumRetries\":$maximumRetries
                                                ,\"numberOfChallenges\":$challenges
                                                ,\"numberOfImagesPerChallenge\":$images
                                                ,\"companyImageUrl\":\"$companyImageUrl\"}");
curl_setopt($ch, CURLOPT_HTTPHEADER,     array(
    "X-Version: 1",
    "Content-Type: application/JSON",
    "Accept: application/JSON",
    "Authorization: Bearer $authToken"
));

$result = curl_exec($ch);
?>