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

Result Info (RESULT_INFO)
Key Type Required Description
status_code Integer Y Holds a an integer value of the response status. i.e.:0 = success, -50 = not authorized (Described in Section Error/Success Messages)
description String Y Holds a text description of the response status. 
{
  "api_job_id": "58657e36-95d5-4352-ab75-6b3a6f16c57b",
  "result_info": {
    "status_code": 0,
    "description": "Success"
  },
  "result": {
    "message_id": "1490005496726001XXXX"
  }
}

 

Result Item (RESULT_ITEM)
Key Type Required Description
message_id String Y The unique ID for the SMS message sent. 
{
  "api_job_id": "58657e36-95d5-4352-ab75-6b3a6f16c57b",
  "result_info": {
    "status_code": 0,
    "description": "Success"
  },
  "result": {
    "message_id": "1490005496726001XXXX"
  }
}

 

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

Result Info (RESULT_INFO)
Key Type Required Description
status_code Integer Y Holds a an integer value of the response status. i.e.:0 = success, -50 = not authorized.

See STATUS_CODES
description String Y Holds a text description of the response status. 
{
  "api_job_id": "b828d4bc-2467-4e19-acbc-059a67168f62",
  "result_info": {
    "status_code": 0,
    "description": "Valid"
  }
}

 

Status Codes (STATUS_CODES)

When responding, the REST API will reply with an HTTP status, response code and a self explanatory message.

The following are the currently available messages.

Response Message Response Code HTTP Status Description
Your authorization token is invalid. -50 401 When the Authorization token found in the header is not valid.
Authorization token not provided. -51 401 When the Authorization token is missing from the header.
Client ref provided already exists. Please provide a different one. -52 422 When requesting a new code and the client ref provided has already been used with the Authorization token provided.
Invalid -53 200 When the code being validated has expired.
Declined -54 422 When the code being validated cannot be found. i.e. it was incorrectly entered by the client.
The code for the provided client ref. and authorization token, was not found. -55 422 The code provided does not match the authorization token and client_ref
No code was provided. -56 422 The code was not provided in request.
Code length too short. -57 422 When the code_length provided is smaller than the minimum.
Code length too long. -58 422 When the code_length provided is bigger than the maximum.
Phone number format is incorrect. -59 422 When format of the phone_number is not a valid mobile number.
No phone number provided in request -60 422 When phone number is missing in the request body.
Callback URL is invalid -61 422 When a non valid URL is provided as callback_url.
No client ref provided in request -62 422 When no client_ref is provided in the request body.
Sender ID is too long. Maximum numeric is 15 & maximum alphanumeric is 11. -63 422 When the sender_id provided in request body is bigger than 15 characters if numeric or is bigger than 11 characters if alphanumeric.
System error – Request data provided was invalid. -64 400 When the request data is in a malformed manner or is not recognizable by the endpoint.
Something went wrong. Make sure data provided is valid and please try again. -65 400 When an error occurred in the system’s back end due to system failure or due to some incorrect data provided.
List of allowed IPs contains one or more invalid IP addresses. -66 400 When the list of IPs available with the authorization token has one or more IPs malformed.
The request IP is not in your list of allowed IP addresses. -67 400 When request IP does not match any one form the list of allowed IP addresses available for the authorization token.
Message template must contain placeholder {#TFA_CODE}. -68 422 When the message template is specified however it does not contain the required placeholder.
Message template exceeds the length of one SMS. -69 422 When the total length of the message (message template + code) is longer than 1 SMS.
Success 0 201 When the request for a new code has been completed successfully.
Valid 0 200 When the code is valid.

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.
Callback Info (CALLBACK_INFO)
Key Type Optional Description
type Enum

N

 The type of network through which the delivery report originated from.

Enum Description
INTERNAL Initial phase of the request
SMS SMS Network
VIBER IM Service on Viber Network
message_id String

N

 The message ID for this message. This should match the message_id returned in the response detailed in  Section Request code – Response Description
status Enum

N

 Enumeration indicating the message’s state at the moment of the callback generation. In case of SMS reports, these match the worldwide SMPP v3.4 standard. As for IM networks, extra custom statuses were added to support these new networks.
Statuses for IM extend, not replace, the SMPP standard.
Currently, the following statuses can be returned:

Enum Description
ACCEPTD Message has been accepted.
DELIVRD Message is delivered to destination.
EXPIRED Message validity period has expired.
DELETED Message has been deleted.
UNDELIV Message undeliverable.
REJECTD Message rejected.
UNKNOWN Message is in an invalid state.
SEEN Message seen by the user on device
timestamp long

N

 UNIX timestamp (i.e. number of seconds from 1-Jan-1970 in UTC) when the delivery was completed.
micro_timestamp long

N

 UNIX micro-timestamp (i.e. number of milliseconds from 1-Jan-1970 in UTC) when the delivery was completed.
to String

N

 Mobile number the SMS was sent to.
Number is in international format and can only be digits between 7-15 digits long. The first digit cannot be a 0.
from String

N

 The sender of the SMS.
If numerical: Contains only digits, between 1-15 digits long.
If alphanumerical: A maximum of 11 characters and minimum of 1 character.
client_message_id String

Y

 The ID originally generated by the client. Maps the original request by the client with the callback, using the client’s own ID.
Minimum length of 1 characters.
error_code short

N

 Error code, else 0.
For a full list of these codes, http://files.fortytwotele.com/api/Fortytwo_Telecom_error_codes.pdf		 
{
  "api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6"",
  "client_job_id": "",
  "data": [
    {
      "type": "SMS",
      "message_id": "1446644528730001XXXX",
      "status": "DELIVRD",
      "timestamp": 1443165174145,
      "micro_timestamp": 1443165174145000,
      "to": "35688000000",
      "sms_from": "Fortytwo",
      "viber_from": "",
      "client_message_id": "reference1",
      "error_code": 943
    }
  ]
}

 

Server Example

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