Loader

Request secure pin authentication


Overview

This command allows you to request a single Secure Pin 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: 
the REST API may respond with various HTTP status codes.


Secure Pin challenge flow
  • Step 1: Make an HTTP POST to have a PIN code sent to a mobile number. You can specify various optional parameters within your request. An API request ID will be returned.
  • Step 2: Use the resulting request ID to validate the PIN your client has received and entered on the website by making a PUT call to the REST API. To do this, append the request ID received for that request to the API URL and then pass the PIN code within your request. 
  • 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

Make a new multi-factor authentication (MFA) request. A message is sent with the challenge to the user (such as a PIN code or a URL to 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

Only accepts pin or grid

customPin no Alphanumeric. Minimum length: 4 characters; maximum length: 8 characters
overrideExpireTime no Defaults to 5 minutes
maximumRetries no Defaults to 1 attempt

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 times a PIN code may be guessed.
  • The customPin parameter can be used to specify a custom PIN code instead of using the system-generated PIN code.

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":"pin","to":"2799900001","overrideExpireTime":"10","maximumRetries":"3"}

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

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

<?php
$to="";
$authType="grid";
$overrideExpireTime="10";
$maximumRetries="3";
$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}");
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

Contact Support

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