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 their mobile phone to verify their identity in order to access a service or a web app. In addition to using their service credentials to access sensitive data, the user also receives a one-time PIN number on his 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 important in these cases:

Phone Number Confirmation

This is the most common use case for 2FA. Usually, during the user registration process, service will ask customer to insert the phone number. In order to make sure the number is correct and not some fake set of numbers inserted to end the registration process quickly, a PIN will be 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 he knows the password and has the phone present.

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 falls in to wrong hands, nothing prevents them from entering the account. This is the case why crucial settings like email for password recovery are protected with 2FA. If malicious user tries to hijack the account by replacing original email, 2FA PIN will be sent out. Unless the phone was stolen with the computer, email update will fail.

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

In another scenario where password has been compromised, suddenly receiving 2FA PIN on the phone is a red alert indicator that someone else knows the password and is trying to use it. Change password action should be taken immediately.

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 is 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 2 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. Aplication Setup - The application represents your service. It’s a 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 will allow you to choose different options and behavior for each use case (like PIN attempts or PIN limits).

To create a new applicaton 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
}

More on the Aplication Setup proccess, how to create a new application, hot to list all applications, get application by ID, and how to update an application find on the dedicated page on our Infobip API Developer Hub.

2. Message template Setup - Message template is the message body with the PIN placeholder that will be 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 will generate a PIN, place the PIN in the message template and finally send 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
}

For more information on how to create a new message template, list all message templates, get a single message template, and update message template refer the Message Template Setup article on the API Reference.

3. After setting up the application, message template and authorization process, you can start generating and sending  PIN codes over 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 refer to the Send and Verify PIN article on the Infobip API Reference.

Related Products

SMS

Reach more customers with faster, more reliable messaging.