Using 2FA API

Infobip's 2FA API follows the standard One-Time Password (OTP) verification process described in General 2FA (OTP) setup.

Before starting the implementation, review the 2FA setup to ensure that you have everything ready to send OTP traffic.

For detailed documentation on the 2FA API, see:

• 2FA API (opens in a new tab) reference - the complete API documentation with additional API calls that are not mentioned in the Implementation steps
• SDKs and tools (opens in a new tab) - SDKs and Postman collections of Infobip's APIs, including the 2FA API

API workflow

The following diagram shows the workflow for the OTP verification process over the 2FA API.

Implementation steps

All of the following steps describe sending One-Time Pins (OTPs) over SMS. For Email and Voice, the general workflow stays the same, but some specifics about the channel are added to the application or template configuration.

Step 1 - Create application

The application represents a set of parameters that configure how 2FA traffic is sent. You can have separate applications for separate services. You may also have separate applications for the same service but different use cases in case they require different configuration.

For example, one application can be used for 2FA upon user registration and another application can be used for 2FA for changing the password. Separating these cases in different applications allows you to choose different options and behavior for each use case.

Request body example:

 
    {
        "name":"User registration",
        "configuration": {
            "pinAttempts": 5,
            "allowMultiplePinVerifications": true,
            "pinTimeToLive": "5m",
            "verifyPinLimit": "1/3s",
            "sendPinPerApplicationLimit": "10000/1d",
            "sendPinPerPhoneNumberLimit": "5/1d"
        },
        "enabled": true
    }
 

When you create your application, you are given an application ID (applicationId) in the response, which you will use later when sending PINs. When you reference an application ID (applicationId) the Infobip system knows what behavior is allowed in that particular use case.

See the 2FA API documentation to learn more about managing applications (opens in a new tab).

Step 2 - Set up message template

Templates describe the message body with the PIN placeholder that is sent to end users. The PIN placeholder, \{\{pin\}\}, must be in the text of the message. You can also configure how the PIN appears, as well as some channel and sender-specific parameters.

You may create many message templates per single application and therefore you can use the same application in different cases (for example, for different languages).

Request body example:

 
    {
        "pinType": "NUMERIC",
        "messageText": "Your pin is {{pin}}",
        "pinLength": 4,
        "senderId": "Infobip 2FA"
    }
 

When you create your message template, you are given the message template ID (messageId), which you will use later when sending PINs. By referencing a message template ID (messageId) the Infobip system generates a PIN, places the PIN in the message template, and finally sends the message with the PIN to the end user.

See the 2FA API documentation to learn more about managing templates (opens in a new tab).

Step 3 - Sending OTP message

After setting up the application and message template, you can start generating OTPs and send them to the desired destination. Make sure that you get the application ID and message template ID from the previous two steps and include them in the request body.

Request body example:

 
    {
      "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
      "messageId": "0130269F44AFD07AEBC2FEFEB30398A0",
      "from": "Infobip 2FA",
      "to": "41793026727"
    }
 

When the message the sent, the PIN ID (pinId) will be in the response. Make sure that you keep the PIN ID because it is used in the next step for PIN verification.

See the 2FA API documentation to learn more about how to send PIN over SMS, Voice or Email (opens in a new tab).

Step 4 - Verifying OTP

OTP verification is completed by providing the PIN ID as a query parameter and the user-provided PIN in the body of the request. This information is used to match the PIN that has been generated on the Infobip side with the PIN that has been entered by the user, which verifies the OTP and so verifies the user's phone number.

Request body example:

 
    {
        "pin": "1598"
    }
 

The final response contains information about whether the user has been verified or not.

See the 2FA API documentation to learn more about verifying OTPs (opens in a new tab).