Loader

Request Secure GridPlus authentication


Overview

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

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

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


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


Secure GridPlus challenge flow
  • Step 1: Make an HTTP POST to have a GridPlus challenge sent to a mobile number. You specify the GridPlus categories as well as various optional parameters within your JSON data packet. An API request ID is returned.
  • Step 2: Use the resulting request ID to check the status of the GridPlus 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 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

Parameter

Required

Description
to yes MSISDN 
from no For sending from a two-way number or specifying a custom sender ID
authType yes

gridplus
overrideExpireTime no Defaults to 5 minutes
maximumRetries no Defaults to 1 attempt
numberOfChallenges yes JSON array of image categories
numberOfImagesPerChallenge no Default is 6 category images
companyImageUrl no Default is Clickatell’s Secure 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 GridPlus 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":"gridplus","to":"2799900001","overrideExpireTime":"10","maximumRetries":"2",
 "numberOfChallenges":["tree","house","dog"],"numberOfImagesPerChallenge":"8",
 "companyImageUrl":"http://www.yourwebsite.com/logo_image.jpg"}

Response
HTTP/1.1 202 Accepted
Content-Type: application/json
{
   "data":{
            "apiRequestId":"gp49d6c09e1ff59ec7dacb225707cad2"
   }
}

 

Sample code
 
PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<?php
$to="";
$authType="gridplus";
$overrideExpireTime="10";
$maximumRetries="1";
$challenges="[\"tree\",\"house\",\"dog\"]";
$images="8";
$companyImageUrl="http://www.yourwebsite.com/logo_image.jpg";
$authToken="<place auth token here>";
 
$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);
?>

Did you find this information informative?

Other Resources

Ask the Community

Visit Stack Overflow to join our community of developers and find the answer you need

Visit Stack Overflow >

Contact Support

Contact our support team and one of our agents will be in touch with you to answer any questions you have

Contact Support >