Thank you for choosing Direct Messenger for your two factor authentication (2FA). This documentation will help you set up the API connection and explains different options available to you. If you are not sure whether our solution is the right one for you, check out our website messenger.ee for more information and don't hesitate to contact us on meryl@messenger.ee or +372 5556 2773.
This API offers the ability to generate and send out 2FA codes and authenticate them.
First you need to contact us on meryl@messenger.ee or +372 5556 2773 and set up an account.
Once you have an account you need to setup your connection to our server. We use an API key to authenticate all incoming requests, if you don't have an API key or you have lost it feel free to contact us.
The setup is fairly simple if you are familiar with POST requests.
The most basic request to send 2FA code through our API requires the following parameters:
api_token - Your API key
receiver - Where to send the 2FA code (phone number)
We will explain those parameters in more detail further down and go over some common mistakes/misunderstandings. Also there are optional parameters and options we will also cover below.
Here's what a basic request like that might look like:
POST https://API_URL/?api_token=YOUR_API_KEY&receiver=372555555555
This request will validate all the fields and on success will store them in our system and send out the message with the 2FA code or in case the validation failed give you back what caused the validation to fail.
A basic request using PHP cURL
// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => [
'Accept:application/json',
],
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => 'API_URL',
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => [
api_token => 'YOUR_API_KEY',
receiver => '372555555555',
]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);
Javascript ajax example
var form = new FormData();
form.append("api_token", "YOUR_API_KEY");
form.append("receiver", "372555555555");
var settings = {
"url": "API_URL",
"method": "POST",
"timeout": 0,
"headers": {
"Accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded"
},
"processData": false,
"mimeType": "multipart/form-data",
"contentType": false,
"data": form
};
$.ajax(settings).done(function (response) {
console.log(response);
});
| Attribute | Description | Default | Type of validation performed if enabled |
|---|---|---|---|
api_token |
Your API key, provided by us, used to authenticate each request. | Always required | |
receiver |
The phone number you want to send the 2FA code to. | Always required | Numeric |
pin_length |
Length of the 2FA code. | Optional. Default length: 6 | Integer. Between 4 and 20 |
After a request, a response is generated. If everything went smoothly you will be notified with a success response.
The success response contains the sms status, the pin that was sent to the client and a pin_id that is used to verify 2FA codes.
PS! Keep the pin_id private. This is used to verify pin -s and should never be given out to your clients!
{
"message": "Success",
"response": {
"pin": "MP3KMJ",
"pin_id": "BEN4KJIK62GNZDVFJCMG",
"sms": "sent"
}
}
If your request fails we will send you back a response with validation errors that you can use to figure out what went wrong.
Some examples of unsuccessful responses
The receiver field was missing
{
"message": "The given data was invalid.",
"errors": {
"receiver": [
"The receiver field is required."
]
}
}
The receiver was an invalid phone number
{
"message": "The given data was invalid.",
"errors": {
"receiver": [
"Invalid number"
]
}
}
The pin_length was too long
{
"message": "The given data was invalid.",
"errors": {
"pin_length": [
"The pin length must be between 4 and 20."
]
}
}
The other feature the API offers is to authenticate users.
This request makes use of the POST method.
The most basic request to send data through our API requires the following parameters:
api_token - Your API key
pin - The 2FA code you are verifying
pin_id - The pin_id we sent you back with the initial 2FA request
Here's what a request might look like:
POST https://API_URL/?api_token=YOUR_API_KEY&pin=PIN_TO_AUTH&pin_id=PIN_ID
Example requesting authentication.
PHP cURL example
// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => [
'Accept:application/json',
],
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => 'API_URL',
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => [
api_token => 'YOUR_API_KEY',
pin => 'PIN_TO_AUTH',
pin_id => 'PIN_ID',
]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);
Javascript ajax example
var form = new FormData();
form.append("api_token", "YOUR_API_KEY");
form.append("pin", "PIN_TO_AUTH");
form.append("pin_id", "PIN_ID");
var settings = {
"url": "API_URL",
"method": "POST",
"timeout": 0,
"headers": {
"Accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded"
},
"processData": false,
"mimeType": "multipart/form-data",
"contentType": false,
"data": form
};
$.ajax(settings).done(function (response) {
console.log(response);
});
| Attribute | Description | Default | Type of validation performed |
|---|---|---|---|
api_token |
Your API key, provided by us, used to authenticate each request. | Always required | |
pin |
2FA code that you are verifying. | Always required | String. Between 4 and 20 |
pin_id |
Corresponding PIN ID we sent back with the initial request. | Always required | String. Size 20 |
The success response contains the auth_status status, the pin that was verified and pin_id that was used to verify the 2FA code.
PS! Keep the pin_id private.
{
"message": "Success",
"response": {
"auth_status": "User has been authenticated",
"pin": "DXYMZO",
"pin_id": "XOK4426WH1HLOG1BOUJK"
}
}
If your request fails we will send you back a response with validation errors that you can use to determine what went wrong.
Some examples of unsuccessful responses
The pin has already been authenticated
{
"message": "The given data was invalid.",
"errors": {
"auth_status": [
"The PIN has already been authenticated"
]
}
}
The pin provided is invalid
{
"message": "The given data was invalid.",
"errors": {
"pin": [
"PIN not found"
]
}
}
The pin and pin_id don't match
{
"message": "The given data was invalid.",
"errors": {
"pin_id": [
"PIN and PIN ID not matching"
]
}
}
The pin has expired (expires after 5 minutes)
{
"message": "The given data was invalid.",
"errors": {
"expire_time": [
"The PIN given has expired"
]
}
}