Introduction

Fortytwo’s Two-Factor Authentication (2FA) API allows you to add an additional layer of security to your users’ login credentials and limits the risk of fraudulent access to your website.

Using our API, you can verify the identity of your users by sending them a one-time password (OTP) via SMS, and asking the user to confirm back the code received, ensuring that the user is the true holder of an account.

2FA is a deceptively simple security process which is used to confirm the identity of an authorised user, involving a combination of any two of the following identifiers:
 

Send SMS Code

Validate Code

Authentication

Endpoints

Request SMS Code

A unique one-time code is sent to the users mobile phone which is either numeric, alpha or alphanumeric. As a client you can choose the character length and case sensitivity of the code as required. The code will automatically default to 6 digits if particular requirements are not defined. As an additional level of security, codes automatically expire within 5 minutes if they are not validated.

Request

POST
https://rest.fortytwo.com/1/2fa

Response

Example

POST /1/2fa HTTP/1.1
Host: https://rest.fortytwo.com
Content-Type: application/json
Authorization: Token 5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Cache-Control: no-cache

{

  "client_ref" : "refnum_1598195",
  "phone_number": "35688000000",
  "code_length": 6,
  "code_type": "alpha",
  "case_sensitive": true,
  "callback_url": "http://example.com/callback",
  "sender_id" : "FortyTwo2FA"
}
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://rest.fortytwo.com/1/2fa",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\n  \"client_ref\" : \"refnum_1598195\",\n  \"phone_number\": \"35688000000\",\n  \"code_length\": 6,\n  \"code_type\": \"alpha\",\n  \"case_sensitive\": true,\n  \"callback_url\": \"http://example.com/callback\",\n  \"sender_id\" : \"FortyTwo2FA\"\n}\n",
  CURLOPT_HTTPHEADER => array(
    "authorization: Token 5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token 5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -H "Cache-Control: no-cache" -d '{

  "client_ref" : "refnum_1598195",
  "phone_number": "35688000000",
  "code_length": 6,
  "code_type": "alpha",
  "case_sensitive": true,
  "callback_url": "http://example.com/callback",
  "sender_id" : "FortyTwo2FA"
}
' "https://rest.fortytwo.com/1/2fa"
import requests

url = "https://rest.fortytwo.com/1/2fa"

payload = "{\n\n  \"client_ref\" : \"refnum_1598195\",\n  \"phone_number\": \"35688000000\",\n  \"code_length\": 6,\n  \"code_type\": \"alpha\",\n  \"case_sensitive\": true,\n  \"callback_url\": \"http://example.com/callback\",\n  \"sender_id\" : \"FortyTwo2FA\"\n}\n"
headers = {
    'content-type': "application/json",
    'authorization': "Token 5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    'cache-control': "no-cache",
    'postman-token': "2c7623ae-09ff-ea0d-092d-d930319b90ce"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

 

Validate Code

Request

POST
https://rest.fortytwo.com/1/2fa/{client_ref}/{sms_code}

Response

Example

Replace the {client_ref} with the client_ref provided in the request. The {code_from_sms} should also be replaced with the code received via SMS

POST /1/2fa/{client_ref}/{code_from_sms} HTTP/1.1
Host: https://rest.fortytwo.com
Content-Type: application/json
Authorization: Token 56a59be7-38da-437f-96c1-634dddXXXXXX
Cache-Control: no-cache


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://rest.fortytwo.com/1/2fa/{client_ref}/{code_from_sms}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "authorization: Token 56a59be7-38da-437f-96c1-634dddXXXXXX",
    "cache-control: no-cache",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token 56a59be7-38da-437f-96c1-634dddXXXXXX" -H "Cache-Control: no-cache" -d '' "https://rest.fortytwo.com/1/2fa/{client_ref}/{code_from_sms}"
import requests

url = "https://rest.fortytwo.com/1/2fa/{client_ref}/{code_from_sms}"

payload = ""
headers = {
    'content-type': "application/json",
    'authorization': "Token 56a59be7-38da-437f-96c1-634dddXXXXXX",
    'cache-control': "no-cache",
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

SDK & Plugins Download

We highly recommend using our REST API directly from your programming language of choice. However we also offer simple SDK for PHP which wraps the REST functionality to kickstart your project. There is also the alternative of installing a WordPress plugin to add Two Factor Authentication to the default WordPress register and login functionality.

Find us on Github and Packagist

PHP SDK

This PHP SDK allows you use our Two Factor Authentication system in your project. This is mostly used as a Composer dependency for PHP 5 projects.

  • Version: 1.3.0
  • Dependencies: PHP >= 5.3.3, Composer
  • Created: 10/05/2016
  • Size: 17.2kB
  • Checksum MD5: e9a333288ac17adf15d042452fa849a1

WordPress Plugin

This wordpress plugin can be found in the WordPress Plugin Directory. It secures your default login & register forms so that an SMS code with a OTP (One Time Password) is sent to the user’s phone and then validated prior to continuation. The plugin has its own configurations to give you a more personalized approach when integrating, such as 2FA required by role, custom SMS code message, code length, code case-sensitivity and more.

  • Version: 1.0.8
  • Compatibility: tested up till WordPress v4.7.3
  • Created: 27/04/2016
  • Size: 2.9MB
  • Checksum MD5: c88bc83876913b6953c23c94548312cb

Callbacks

Delivery Reports and any other relevant intermediary status are signalled back to the client using an HTTP callback. The URL invoked is obtained from the “callback_url” field in the original message request.

The request generated to this URL is described below. The endpoint, on the client side, must therefore fully support this kind of request and respond accordingly.

If no callback_url was specified in the request, no callback is generated.

Whitelist callback server

You may need to configure your firewall to whitelist traffic from these IP addresses:

IPv4: 80.252.167.60

Note that these IPs can change in the future.

SSL Support

The use of SSL on the client’s callback server is optional, i.e. both HTTP and HTTPS schemes are supported. However, if HTTPS validation fails, the callback is treated as failed. For information on how failures are handled, see Callback failure below.

 

Response HTTP Status Code

The HTTP Callback on your server should return the correct HTTP Headers containing 200 OK. If the client’s server is unreachable or does not return a 200 OK, the callback is queued to be retried again. After three failed attempts, with an interval of 5 minutes between them, the callback is discarded.

Server Example

Examples for Servers that accept HTTP POST Callbacks
$postRawData = file_get_contents("php://input");
$json = json_decode($postRawData, true);
var_dump($json);