Two Factor Authentication
An authentication factor is a category of security credential used to verify a user's identity and authorization before allowing that user to gain access to their account, send communications, or request data from a secured network, system, or application.
Two-factor authentication (2FA) is a security process where users must provide two different authentication factors to verify their identity and access their account. This process ensures better protection of a user's personal information, credentials, and other assets, while also improving the security around the resources the user can access.
Certainly, two-factor authentication provides a higher level of security than authentication methods that rely on only one authentication factor (single-factor authentication), where the user provides only one factor (usually a password or PIN). A 2FA method would require a user to provide not just a password or a PIN, but a second factor, ranging from a biometric factor (a facial, retinal, or fingerprint scan) to a possession factor (a one-time use code sent to a smartphone known to be in a user's possession).
Now, 2FA adds an additional layer of security to the authentication process by making it harder for attackers to gain access to a person's devices or online accounts because knowing the victim's password alone is not enough to pass the authentication check. Two-factor authentication has long been used to control access to sensitive systems and data, and online service providers are increasingly using 2FA to protect their users' credentials from being used by hackers who have stolen a password database or used phishing campaigns to obtain user passwords.
Managing Two Factor Authentication
A two-factor authentication code is a one-time code generated to prove a user's identity when they try to access an online account or system. The code would be sent via text message or by an automated phone call to a phone number associated with the user. Upon entering the two-factor authentication code, the user gains access to their online account.
NOTE
These codes often expire after a short amount of time if not used.
The API provides functions to create a new two factor configuration (code generator), request a new two factor authentication code and provide a validation status for that specific request. Additionally there are functions to get a list of code generators previously configured. Cancel and verify status code is currently supported via API.
Our RESTful API lets developers easily integrate Two Factor Authentication into their solutions.
Through the following diagram we explain the 2FA security process between your Project and Digital Engagement API:

-
User enters the phone number into the client’s application (mobile or web)
-
Application sends a request for the code with the user’s phone number to Platform . That is, initiate Two Factor Authentication Process by sending the Mobile Number.
-
Platform proceeds to create a code generator which helps to configure the code that will be sent to the end user.
-
Platform delivers the SMS with the security code to the final user.
-
Platform generates the request ID, and sends the request ID back to the application.
-
User enters the received security code provided by Platform into the application.
-
Application sends the verification request with the security code and request ID to Platform .
-
Validate if the end user entered the correct code or not. That is, if there is a match between the request iD that Platform provided to the application and the security code, the user will be considered as a valid user, otherwise will be considered as a invalid user.
-
Platform verifies the received code and sends the response (validation status) to the application.
The steps to configure, send and verify a code are the following:
-
Configure a code generator
-
Request and Send the code (via SMS or Email) to your customers
-
Validate User
Creating Code Generator
Code Generator is a security feature for your Application used with two-factor authentication. You can add an authentication factor linked to a channel (SMS or Email for example). When a user signs up or logs into your application a numeric code is sent to their mobile device either via SMS, email or push notification or through an authentication app. For this reason, the first step is to create the code generator and configure the code that will be sent to the user.
At this point, you need to define the code length, the expiration time of the code, the delivery channel in which the code will be sent and the message body with the code placeholder that is sent to the end user.
You are currently able to delivery the security code through two delivery channels:
-
SMS : SMS is the most popular channel for two-factor authentication (2FA). That's because most people can receive text messages and onboarding is seamless.
-
Email : One time passcodes (OTP) sent to email can help protect your users if their password is brute-forced or phished. Like SMS, it doesn't require downloading another app so onboarding will be quick and seamless.
Code Generator works on your mobile device as long as you have a valid number to receive text messaging (SMS) or an Internet connection for receiving PUSH and Emails and it can be reused as many times as you need.
When you create a Code Generator, the request body contains the following data:
HTTP Request : POST /v1/2fa
{
"codeLength": 6,
"expirationMinutes": 10,
"channels": [
{
"type": "SMS",
"shortcode": "1234",
"message": "your verification code is {0}"
},
{
"type": "EMAIL",
"from": "[email protected]",
"subject": "Verification code",
"message": "your verification code is {0}"
}
]
}
The parameters presented in the request body example when creating the Code Generator are the following:
Parameter | Description |
---|---|
codeLength | Security code length. The security codes used for two-factor authentication are a minimum of 6 digits. |
expirationMinutes | Security code expiration time in minutes. |
channels | Contains the information of the channels to be used for the code delivery. Only ONE channel can be chosen when generating a code. |
type | Define the channel from where the code will be sent. Currently supports independent channels for 2FA: SMS , Email . |
shortcode | Sender of the 2FA SMS message. You must be registered in the SMS delivery channel to get a valid shortcode (SMS sender). |
from | Sender of the 2FA Email message. You must be registered in the Email delivery channel to get a valid email sender. |
subject | Subject for Email channel. |
message | Text of a message that will be sent. It can contain placeholders that will be replaced upon sending. Message text must contain a {0} placeholder which then will be replaced by the code generated.Placeholder : Key value pairs that will be replaced during message sending. |
When you have created the code generator, the response body contains the following data if you configured the code generator with the SMS delivery channel for example:
{
"meta": {
"timestamp": 1618100570108,
"transactionId": "1beeee1f-4fcb-471d-af9b-d74413e3d28f"
},
"data": {
"id": 78,
"codeLength": 6,
"expirationMinutes": 10,
"channels": [
{
"shortcode": "1234",
"text": "your verification code is {0}",
"type": "SMS"
}
]
}
}
We only describe the additional parameters that are generated when making the request.
To consult each description parameter (not additional parameters) displayed in the response body example, go to the parameters presented in the request body example when creating the code generator.
The additional parameters presented in the response body example when creating the code generator are the following:
Parameter | Description |
---|---|
data | Data contains the code generator basic information. |
id | 2FA code generator ID. |
Getting Code Generator
When the Code Generator is previously created, you proceed to get the specific data from a single code generator.
HTTP Request : GET /v1/2fa/{id}
To get a code generator, you need to provide the unique identifier of the code generator you want to retrieve the information.
Required Parameter | Description |
---|---|
id | You must provide the identifier of the Code Generator to get the details of a single instance of this configuration. |
Generating and Sending Security Code
After setting up the code length, expiration time, delivery channel where the code will be sent, shortcode and message, you can start generating and sending via SMS or Email the security code to the provided destination address. As long as the User has a mobile phone or an email defined you may send the user a code.
To generate a security code, you only need to specify the code generator id you want to use, the channel where you want the code to be sent and the phone number or email address to whom the 2FA message will be sent.
Once the code has been generated and sent to the recipient, you will be provided with a request_id
and the user will be provided with a security code
that he requested.
NOTE
Each code is only sent through one delivery channel.
In case the user does not receive the requested code, he can request a new code on a different delivery channel. For example, this endpoint allows you to send the code via SMS but if the user doesn't receive the code, you can define the Email channel from the channel
parameter to send the new code via Email to the receiver
(user).
Before sending the code via SMS or Email, you need to create the code generator to configure the SMS or Email delivery channel.
The User must already have a valid mobile phone or email address for this to succeed.
HTTP Request : POST /v1/2fa/{id}/codes
When you request a new two factor authentication code, the request body contains the following data:
{
"channel": "SMS|EMAIL",
"receiver": "1234|[email protected]"
}
The parameters presented in the request body example when generating the security code ode are the following:
Parameter | Description |
---|---|
channel | Define the channel from where the code will be sent. Only ONE channel can be chosen per request. Currently supports independent channels for 2FA: SMS , Email . |
receiver | Phone number to which the 2FA message plus security code will be sent if you choose the SMS channel. Email to which the 2FA message will be sent plus security code if you choose the email channel. |
When you generated the security code, the response body contains the following data:
{
"meta": {
"timestamp": 1618181833535,
"transactionId": "a9e0e8d4-8bb0-46f2-9a1c-955f9c"
},
"data": {
"requestId": "1e24a4d6-e2fb-317d-a79e705"
}
}
The parameters presented in the response body example when generating and sending the security code are:
Parameter | Description |
---|---|
data | Data contained when the code is sent. |
requestId | 2FA request ID. |
To generate and send the security code to the user, you need to provide the unique identifier of the code generator you want to use.
Required Parameter | Description |
---|---|
id | You must provide the identifier of the Code Generator to generate and send the message plus security code. |
Validating User
Once the code has been generated and sent to the user via SMS or email, you proceed to validate the user.
When the user enters the security code to your application, you can carry out the following actions :
-
Verify the security code to validate the user.
-
Cancel the security code.
-
Check the Status of the security code.
In order to perform each action as mentioned above, you need to provide the request ID and the security code of the user once he entered it into your app.
HTTP Request : PATCH /v1/2fa/{id}/codes
When you want to verify the user, cancel the code or check the status code, the request body contains the following data:
{
"action": "VERIFY|verify|CANCEL|cancel|STATUS|status",
"requestId": "HFTHJDL445HDBASL",
"code": "1234"
}
The parameters presented in the request body example when validating the user are the following:
Parameter | Description |
---|---|
action | The API provides the following actions: - VERIFY : verify the security code to validate the user.- CANCEL : cancel the security code.- STATUS : status of the security code. |
requestId | 2FA request ID. ID of the security code that has to be verified. |
code | Security code to verify. |
When you verified the security code, the response body contains the following data:
{
"meta": {
"timestamp": 1597166699457,
"transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
"explain": "valid code"
}
}
The parameters presented in the response body example when validating the user are the following:
Parameter | Description |
---|---|
explain | valid code : Indicates if the security code was successfully verified. |
To validate the user, cancel the code or check the status code, you need to provide the unique identifier of the code generator you want to use, the security code and the request Id.
Required Parameter | Description |
---|---|
id | You must provide the identifier of the Code Generator to verify the user, cancel the code or check the status code. |
requestId | 2FA request ID. ID of the security code that has to be verified. |
code | Security code to verify. A valid Two Factor verification code. This value should be provided by the User to verify they are able to produce codes using an application or receive them using their mobile phone. |
Updated about 1 year ago