Blog Page

Two factor authentication API with phone call

Text message is by far most popular method for doing two factor authentication by phone call. But here are some situations where this is not possible and ways to solve it.

Two factor authentication (2FA) using telephone can be made in several different ways. One, most popular is of course by sending a text message. It is fast and easy way to verify the authenticity of the other party. However, there are cases when SMS is not the best option or even not possible at all, like;

• if the remote party is unable to receive text messages, like fixed lang line phones;
• if increased security is needed: short messages might be stored on users phones and their contents viewed by third parties, whereas voice message does not persist after once spoken;
• accessibility: for persons who may have difficulties to read;
• cost issues: for many destinations a cost of the voice call of halt a minute is still lower than sending a text message

In these cases sending a voice call with prerecorded or text-to-speech message is an alternative solution.

There are two main ways to send authorization code over a phone call: either by a prerecorded voice message or by text-to-speech. The advantages of each method include:

• for text-to-speech:
  • much easier and faster deployment: no need to prerecord voice messages;
  • no additional third-party costs for text to speech conversion;
  • no need to worry about language constructs if sending multi-digit numbers;
• for prerecorded messages:
  • larger langauge coverage: may record messages in the languages where text to speech is not available;
  • higher reliability: text-to-speech engine more probable to be unavailable than an audio file stored locally;

Here are examples of API call for the methods described above.

First example is for a text-to-speech message which will send authentication code 123456 in English. For better user experience it will repeat the message two times:

POST /voice/call/play 


{
  "to": "12125551212",
  "from": "me",
  "playlist":
    [
      {
        "play": "Your code is 123456",
        "type": "tts",
        "options":
          {
            "language": "en-US",
            "gender": "female",
            "say-as": "digits"
          }
      },
      {
        "play": "Your code is 123456",
        "type": "tts",
        "options":
          {
            "language": "en-US",
            "gender": "female",
            "say-as": "digits"
          }
      }
    ],
  "carrier_id": "74445609"
}

The other example uses files stored at the location http://server.domain.com/voices/ . Here also they speak the same code two times:

POST /voice/call/play 

{
  "to": "12125551212",
  "from": "me",
  "playlist":
    [
      { 
        "play": "http://server.domain.com/voices/your-code-is.wav"
      },
      {
        "play": "http://server.domain.com/voices/1.wav"
      },
      {
        "play": "http://server.domain.com/voices/2.wav"
      },
      {
        "play": "http://server.domain.com/voices/3.wav"
      },
      {
        "play": "http://server.domain.com/voices/4.wav"
      },
      {
        "play": "http://server.domain.com/voices/5.wav"
      },
      {
        "play": "http://server.domain.com/voices/6.wav"
      },
      { 
        "play": "http://server.domain.com/voices/your-code-is.wav"
      },
      {
        "play": "http://server.domain.com/voices/1.wav"
      },
      {
        "play": "http://server.domain.com/voices/2.wav"
      },
      {
        "play": "http://server.domain.com/voices/3.wav"
      },
      {
        "play": "http://server.domain.com/voices/4.wav"
      },
      {
        "play": "http://server.domain.com/voices/5.wav"
      },
      {
        "play": "http://server.domain.com/voices/6.wav"
      }
    ],
  "carrier_id": "74445609"
}

Notes regarding above examples:

• carrier_id tag is described in a previous post entry about SIP routing.
• there is a say-as tag in the text to speech example. It is needed to indicate to text to speech engine to say digits individually instead of pronouncing a six-digit number as a whole.