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. 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:

  1. User enters the phone number into the client’s application (mobile or web)

  2. 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.

  3. Platform proceeds to create a code generator which helps to configure the code that will be sent to the end user.

  4. Platform delivers the SMS with the security code to the final user.

  5. Platform generates the request ID, and sends the request ID back to the application.

  6. User enters the received security code provided by Platform into the application.

  7. Application sends the verification request with the security code and request ID to Platform .

  8. 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.

  9. 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, Email or WhatsApp) 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, Email or WhatsApp). When a user signs up or logs into your application a numeric code is sent to their mobile device either via SMS, Email or WhatsApp 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.

  • WhatsApp: If your app offers users the option to receive one-time passwords or verification codes via WhatsApp, you must use an WhatsApp Authentication Template.

    📘

    NOTE

    Before creating a code generator, you need to create a Whatsapp Authentication Template. For more details go to the “Two factor Authentication (WhatsApp)” use case to know how to integrate WhatsApp with two Factor Authentication.

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}"
    },
    {
      "type": "WHATSAPP",
      "address": "181920",
      "templateId": "242528",
      "placeholder": "code"
    }
  ]
}

The parameters presented in the request body example when creating the Code Generator are the following:

ParameterDescription
codeLengthSecurity code length.

The security codes used for two-factor authentication are a minimum of 6 digits.
expirationMinutesSecurity code expiration time in minutes.
channelsContains the information of the channels to be used for the code delivery. Only ONE channel can be chosen when generating a code.
channels.typeDefine the channel from where the code will be sent.

Currently supports independent channels for 2FA: SMS , EMAIL, WHATSAPP.
channels.shortcodeOnly applies to the "SMS" type.

Sender of the 2FA SMS message.

You must be registered in the SMS delivery channel to get a valid shortcode (SMS sender).
channels.messageOnly applies to the "SMS" and "EMAIL" type.

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.
channels.fromOnly applies to the "EMAIL" type.

Sender of the 2FA Email message.

You must be registered in the Email delivery channel to get a valid email sender.
channels.subjectOnly applies to the "EMAIL" type.

Subject for Email message.
channels.addressOnly applies to the "WHATSAPP" type.

Phone number of the sender.

Phone number provided during the WABA account setup will be used as the sender of the notification message.

Only accepts numeric characters. Do not include the "+" sign.
channel.templateIdOnly applies to the "WHATSAPP" type.

Unique identifier of the WhatsApp Authentication Template.
channel.placeholderOnly applies to the "WHATSAPP" type.

The Body message (defined by META) contains a placeholder (“code”)which then will be replaced by the code generated.

When you have created the code generator, the response body contains the following data if you configured the code generator with the SMS, Email, and WhatsApp in a single API request:

{
  "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"
      },
      {
        "subject": "Verification code",
        "from": "[email protected]",
        "text": "your verification code is {0}",
        "type": "EMAIL"
      },
      {
        "placeholder": "code",
        "address": "181920",
        "templateId": "242528",
        "type": "WHATSAPP"
      }
    ]
  }
}

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:

ParameterDescription
dataData contains the code generator basic information.
id2FA code generator ID.

Generating and Sending Verification 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.

🚧

WARNING

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 or another channel but if the user doesn't receive the code, you can define the WhatsApp channel from the "channel" parameter to send the new code to the receiver .

The User must already have a valid mobile phone or email address for this to succeed.

HTTP Request : POST /v1/2fa/{id}/codes

In this API call you need to provide the unique identifier (“data.id”) of the code generator previously created.

{
  "channel": "SMS|EMAIL|WHATSAPP",
  "receiver": "+525500000000|[email protected]|+525500000000"
}

The parameters presented in the request body example when generating the security verification code are the following:

ParameterDescription
channelDefine 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, WHATSAPP.
receiverSMS: Phone number to which the 2FA message plus verification code will be sent.

Email: Email to which the 2FA message will be sent plus verification code.

WhatsApp: Phone number to which the 2FA message plus verification code will be sent.

When you generated the verification code, the response body contains the following data:

{
  "meta": {
    "timestamp": 1618181833535,
    "transactionId": "a9e0e8d4-8bb0-46f2-9a1c-955f9c"
  },
  "data": {
    "requestId": "14r578t-a257-u789-e347920"
  }
}

The parameters presented in the response body example when generating and sending the verification code are:

ParameterDescription
dataData contained when the code is sent.
requestId2FA request ID.

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 verification code that requested.

Validating Verification Code

Once the code has been generated and sent to the user via SMS, Email or WhatsApp, you proceed to validate the verification code.

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 this example, we'll solely verify the verification code.

HTTP Request : PATCH /v1/2fa/{id}/codes

In this API call you need to provide the unique identifier (“data.id”) of the code generator and the unique identifier (“data.requestId”) of the request previously created.

Prior to validating the user, it's necessary to initially verify the status of the verification code.

{
  "action": "status",
  "requestId": "14r578t-a257-u789-e347920"
}

Request Body Parameters

ParameterDescription
actionApply one the following actions to the verification code:

- “status”: know the status of the verification code.

- “verify”: verify the verification code to validate the user.

- “cancel”: cancel the verification code.

For this example, we set the “status” parameter.
requestIdUnique identifier of the two factor authentication request. That is, this is the ID of the verification code that has to be verified.
{
  "meta": {
    "timestamp": 1707243156412,
    "transactionId": "6ae15fa5-1e97-45dc-be65-275f51967fef"
  },
  "data": {
    "id": 534,
    "userID": "+525500000000|[email protected]|+525500000000",
    "token": "135385",
    "requestID": "14r578t-a257-u789-e347920",
    "expirationDate": "2024-02-06T01:44:37.020949",
    "validationDate": null,
    "validationChannel": "SMS|EMAIL|WHATSAPP",
    "status": "PENDING"
  }
}

Response Body Parameters

ParameterDescription
data.idUnique identifier of the status API call.
data.userIDDestination phone number for your authentication template and verification code.

Numbers are specified in E.164 format → (‘+’ and a country code).
data.tokenVerification code that was sent to the end user.
data.expirationDate
data.validationDateDate on which the verification code has been valid.
data.validationChannelChannel from where the verification code was sent:

- “SMS”
- “EMAIL”
- “WHATSAPP”
data.statusStatus of the verification code.

- “VALIDATED”: The verification code has been confirmed as valid.

- “PENDING”: The verification code has not been confirmed as valid yet.

- “EXPIRED”: The verification code has expired.

Because the verification code is in “PENDING” status, we proceed to validate the code.

📘

NOTE

In this API Call, the user needs to enter their verification code to valid the code.

We acquired that code from the previous request to provide you with a clearer understanding of its status and validation.

{
  "action": "verify",
  "requestId": "14r578t-a257-u789-e347920",
  "code": "135385"
}

Request Body Parameters

ParameterDescription
actionApply one the following actions to the verification code:

- “status”: know the status of the verification code.

- “verify”: verify the verification code to validate the user.

- “cancel”: cancel the verification code.

For this example, we set the “verify” parameter.
requestIdUnique identifier of the two factor authentication request. That is, this is the ID of the verification code that has to be verified.
codeVerification code that has to be verified.
{
  "meta": {
    "timestamp": 1707252519688,
    "transactionId": "42421f-96f60",
    "explain": "valid code"
  }
}

Response Body Parameters

ParameterDescription
explainValid verification code.

“valid code”: the verification code entered is valid.