Two Factor Authentication

Use two-factor authentication (2FA) to send and validate a one-time verification code through SMS, email, or WhatsApp.

An authentication factor is a credential used to verify a user's identity and authorization before they access an account, send communications, or request data from a secured system. 2FA requires two factors: something the user knows, such as a password or PIN, and a second factor, such as a biometric scan or a one-time code sent to a device they possess.

Because a password alone is not enough to pass the authentication check, 2FA helps protect accounts when passwords are stolen through a compromised password database or phishing.

Managing Two Factor Authentication

A two-factor authentication code is a one-time code that proves a user's identity when they access an online account or system. Send the code through an available delivery channel, then validate the code that the user enters in your application.

📘

NOTE

These codes often expire after a short amount of time if not used.

Use the API to create a code generator (a reusable configuration for verification codes), request a verification code, and check, verify, or cancel a request. You can also list previously configured code generators.

The following diagram shows the 2FA process between your application and the Communications Platform API:

1. The user enters their phone number in your mobile or web application.
2. Your application requests a verification code from the platform.
3. The platform uses the code generator to configure code delivery.
4. The platform sends the verification code through the selected channel.
5. The platform returns a request ID to your application.
6. The user enters the received verification code in your application.
7. Your application sends the verification code and request ID to the platform.
8. The platform compares the verification code with the request ID.
9. The platform returns the validation status to your application.

Complete the 2FA flow in this order:

1. Configure a code generator.
2. Request and send the code through SMS, email, or WhatsApp.
3. Validate the user.

Creating Code Generator

Create a code generator to define how your application sends verification codes. Configure the code length, expiration time, delivery channel, and message body, including the code placeholder.

Choose one of the following delivery channels:

• SMS: Send the verification code in a text message.

• Email: Send the verification code in an email.

• WhatsApp: Send the verification code with a WhatsApp Authentication Message Template.

  📘

  NOTE

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

Reuse a code generator whenever you need to send a verification code with the same configuration.

Create a code generator with the following request body:

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:

If you configure SMS, email, and WhatsApp in one request, the response body contains the following data:

{
  "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"
      }
    ]
  }
}

The following table describes only the additional response parameters. Refer to the request-body parameter table for the remaining fields.

The additional parameters presented in the response body example when creating the code generator are the following:

Generating and Sending Verification Code

After you configure a code generator, request a verification code for a recipient with a valid phone number or email address.

Provide the code generator ID, delivery channel, and recipient phone number or email address. The API returns a requestId, and the recipient receives the verification code.

🚧

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 .

Make sure the recipient has a valid phone number or email address.

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

Provide the unique identifier (data.id) of the code generator that you 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:

After the API generates and sends 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:

Store the returned requestId; you need it to check, verify, or cancel the verification-code request.

Validating Verification Code

After the user receives a verification code through SMS, email, or WhatsApp, validate it in your application.

Use one of the following actions:

• Verify the code and validate the user.
• Cancel the code.
• Check the code status.

This example checks the code status before verifying the code.

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

Provide the unique identifier (data.id) of the code generator and the unique identifier (data.requestId) of the previously created request.

Check the verification-code status before you validate the user.

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

The parameters presented in the request body example when verifying the status of the verification code are the following:

After you check the verification-code status, the response body contains the following data:

{
  "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"
  }
}

The parameters presented in the response body example when verifying the status of the verification code are the following:

Because the verification code has a PENDING status, you can 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"
}

The parameters presented in the request body example when validating the code are the following:

After you validate the code, the response body contains the following data:

{
  "meta": {
    "timestamp": 1707252519688,
    "transactionId": "42421f-96f60",
    "explain": "valid code"
  }
}

The parameters presented in the response body example when validating the code are the following: