Two-Factor Authentication over API

Two-factor authentication (2FA) is an extra layer of security that requires users to use both their online password and mobile phone to verify their identity to access a service or web app. In addition to using their service credentials to access sensitive data, the user also receives a one-time PIN number on their token or via SMS or Voice.

The one-time PIN (OTP) number is generated and sent to the user’s mobile phone. The user receives the OTP and types it into the application to confirm their identity. If the PIN number that was sent out to the user matches the one that is received, the user is allowed to continue with the process.

Two-factor authentication is highly important in these cases:

Phone Number Confirmation

The most common 2FA use case. Usually, during the user registration process, service will ask customer to enter the phone number. To make sure the number is correct and not some fake set of numbers inserted to end the registration process quickly, a PIN is sent to that number. By retyping the PIN back into the application, the phone number is confirmed.

Login Form

During the login process, after successfully entering username and password, application sends out PIN to the phone number the customer supplied during the 2FA activation process. If PIN is retyped back into the app, this confirms with some level of certainty that the real account owner is trying to log in, since they know the password and have the phone present at that moment.

Account Settings Update

Many users choose to remember passwords via browsers or other password manager tools. Remember me options are very often used on personal computers and if such computer ends up in the wrong hands, nothing prevents them from entering the account. This is why crucial settings like email for password recovery are protected with 2FA. If a malicious user tries to hijack the account by replacing the original email, 2FA PIN will be sent out, and unless the phone was stolen with the computer as well, email update will fail.

In this scenario, the real owner still has a chance to regain access to their account by using password recovery over email option.

Transaction Confirmation

Similarly, to account settings, 2FA PIN number should be required just before a financial transaction or some other type of high-risk execution.
By confirming your identity by PIN, the process can be finalized.

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

2. Application sends a request for the PIN code with the user’s phone number to Infobip

3. Infobip generates the PIN and PIN ID, and sends the PIN ID back to the application

4. Infobip sends Number lookup request to the MNO

5. Infobip receives Number Lookup response from the MNO

6. Infobip sends Number Lookup response to the application

7. If the Number Lookup result is valid, Infobip generates the PIN code and sends it via SMS

8. MNO delivers the SMS with the PIN code

9. Infobip receives the Delivery report for sent message

10. User enters the received PIN code into the application

11. Application sends the verification request with the PIN code and PIN ID

12. Infobip verifies the received PIN and sends the response to the application

Setup consists of two parts and requires only two API calls to complete the setup process⁠ - application setup and message template setup. Later, you will reuse message template(s) to send out PINs.

IMPLEMENTATION STEPS

Steps over API

1. Application setup - the application represents your service. It’s good practice to have separate applications for separate services. You may also have separate applications for the same service but different use cases. For example, 2FA for login may be represented as one application and 2FA for changing password as another. Separating use cases in different applications allows you to choose different options and behavior for each use case (like PIN attempts or PIN limits).

To create a new application follow the request example:

{
    "name":"Test application BASIC",
    "configuration": {
        "pinAttempts": 10,
        "allowMultiplePinVerifications": true,
        "pinTimeToLive": "15m",
        "verifyPinLimit": "1/3s",
        "sendPinPerApplicationLimit": "10000/1d",
        "sendPinPerPhoneNumberLimit": "3/1d"
    },
    "enabled": true
}

Read more about the Application Setup proccess, how to create a new application, how to list all applications, get application by ID, and how to update an application.

2. Message template setup - message template is the message body with the PIN placeholder that is sent to end users. You may create many message templates per single application and therefore use the same application for different use cases or different languages. When you create your message template, you will be provided with the message template ID, which you will be using later when sending PINs. By referencing a message template ID, our system generates a PIN, places the PIN in the message template and finally sends the message with the PIN to the end user.

Request example:

{
  "pinType":"NUMERIC",
  "pinPlaceholder":"<pin>",
  "messageText":"Your pin is <pin>",
  "pinLength":4,
  "senderId":"Infobip 2FA",
  "language": "en",
  "repeatDTMF": "1#",
  "speechRate": 1
}

Read through the Message Template Setup article on how to create a new message template, list all message templates, get a single message template, and update message template.

3. After setting up the application, message template and authorization process, you can start generating and sending PIN codes via SMS to the provided destination address.

Request example:

{
  "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
  "messageId": "0130269F44AFD07AEBC2FEFEB30398A0",
  "from": "InfoSMS",
  "to": "41793026727"
}

To learn more on how to send PIN over SMS, resend PIN over SMS, send PIN over Voice, resend PIN over Voice, and verify PIN kindly refer to the Send and Verify PIN article available on the Infobip API developers hub.