Smart 2FA

Overview

Smart 2FA API lets you to send One Time Passowrd (OTP) using SMS, Voice or email.

2FA allows you to add a second layer of security to your Application in addition to the user-id and password. The flexibility of using any channel makes sure your users get OTP even when they experience issue with one of the channels.

User enters your application

User visits your website or mobile app and attempts to log into his account, authorize a transaction, or perform another action that requires two-factor authentication from a new device.

User is prompted to enter his phone number

CPaaS receives the login attempt and prompts the user to enter his phone number in order to authorize the new device.

PIN code is sent to the user via SMS, phone call or email depending on API called

Once the user enters a valid phone number, from your application you will need to ask CPaaS to send a verification code to that phone number by using the HTTP REST API Call Below.

Categories

2FA can be broadly classified into four categories:

  • Send

  • Verify

  • Control

  • Session Detail Record

Sending One-Time Passwords - API Reference

Sending a verification code requires basic authorization that includes your account SID and auth token. Below is the format you have to use in order to send a verification code to the user’s phone number.

Base Resource URI

https://$DOMAIN

Verification Code Resource URI

/2fa/send

Supported Operations

HTTP POST: Send a verification code through SMS, phone call or email to the specified destination.

Request Parameters

Parameter Description

service (Required)

The name of your service.

from (Required)

The source address that is making a call, or sending the SMS or email containing the verification code.

to (Required)

The destination address to send the OTP message containing the verification code.

body (Required)

The content of the OTP message. Use {code} as a placeholder for the location of the verification code in your SMS content. This {code} will be replaced automatically with a random code generated by the system

channel (Optional)

A method for sending OTP message. There are 3 options: sms, call, email. If not passed, default is sms.

accountSid (Optional)

OTP message will be sent on behalf of given accountSid. The accountSid has to be valid sub-account.

subject (Required in email channel)

Email subject for the OTP message, it’s required only in email channel.

language (Optional)

Text-to-Speech (TTS) language for announcing OTP message over call channel. AWS Polly is default TTS engine. To use another engine, use format like : <engine>.<language-code> for example: awspolly.ja-JP. More information about language, please visit Say-RCML

repeat (Optional)

Number of times the TTS OTP message will be played. It’s only required in call channel, default value is 1.

length (Optional)

Number of digits for OTP. By default, 6 digits number will be generated for OTP code.

voice (Optional)

Man or woman voice for TTS call channel.

timeout (Optional)

Time in seconds for which OTP is valid. Post timeout period, OTP is automatically canceled if still not successfully verified. Default is 300 seconds.

guardTime (Optional)

If send is called again to send new OTP passing same service and to parameter while previous OTP generated is still valid, the previous OTP is Canceled and new OTP is sent. However if guardTime (in seconds) parameter is passed in send request, old OTP is valid for guardTime and then cancelled. This is to accomodate scenarios where the underlying SMS, Call or email channel may be slow to deliver the message and by the time new OTP is generated, user might have received old OTP.

Response

Responde Body

Description

code

Sub error code for the request.

message

Message for describing sub error code.

requestID

The unique OTP request identifier for the OTP request.

Response Parameters

send API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code In addition below are the Error’s that it can return

Error Code

HTTP Status

Error Message

Description

Category

453

404

Too many OTP request to same destination Number

OTP is sent to same destination number within 1 min of previously sent. 2FA system limits number of OTP sent to same number to maximum one per min.

Send

Example

{
    "service" : "2FA", // the name of your service
    "from" : "+XXXXXXXXX", // the SMS sender phone number
    "to" : "+XXXXXXXXXX", // the SMS recepient phone number
    "body": "Your verification code is: \{code}" // SMS body, containing the verification code
}

From the bash terminal you can run the command below:

curl -X POST \
  https://$DOMAIN/2fa/send \
  --user  ' \{your_account_SID}:\{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "service" : "2FA",
    "from" : "XXXXXXXXXXX",
    "to" : "ZZZZZZZZZZZ",
    "body": "Your verification code is: \{code}"
  }'

If send is successful, below is the response returned:

{"code":200,"message":"OK","requestID":"OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"}

Verifying One-Time Passwords - API Reference

User receives the one-time PIN code via SMS, phone call or email, gets back to your application and enters it in order to complete the verification process. Verifying the code is simple and requires basic authorization that includes your account SID and auth token.

Base Resource URI

https://$DOMAIN

Verification Code Resource URI

/2fa/verify

Supported Operations

HTTP Method: POST: Verifies the code that was sent through SMS, phone call or email to the destination

Request Parameters

Parameter

Description

service

The name of your service.

requestId

The requestID was received when initiating OTP message.

accountSid

If OTP message was initiated on behalf on accountSid, verify will require to have same accountSid to be able to verify the OTP request.

code

The verification code that was sent to the user through SMS.

Response

Responde Body

Description

code

Sub error code for the request.

message

Message for describing sub error code.

requestID

The unique OTP request identifier for the OTP request.

Response Parameters

verify API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return

Error Code

HTTP Status

Error Message

Description

Category

470

404

Invalid OTP Unique Id

Verify is called for UniqueID which is not present in-system

Verify

471

409

OTP is already verified

Verify is called for UniqueId which is present in-system but already verified (successfully)

Verify

472

409

OTP is expired

Verify is called for UniqueId which is present in the system but expired

Verify

473

409

OTP is cancelled

Verify is called for UniqueId which is present in the system but cancelled

Verify

474

401

Invalid OTP Code

Verify is called for UniqueId which is present and Invalid Code is passed

Verify

Example

{
    "service" : "2FA", // the name of your service
    "requestId" : "OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",  // the unique OTP Id generated when send was called
    "code": "XXXXXX" // the verification code
}

From the bash terminal you can run the command below:

curl -X POST \
  https://$DOMAIN/2fa/verify \
  --user  ' \{your_account_SID}:\{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "service" : "2FA",
    "requestId" : "OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    "code": "XXXXXX"
}

Control

Control API allows App developers to cancel already sent API or resend the OTP (resend is in roadmap)

Cancel One-Time Passwords - API Reference

Base Resource URI

https://$DOMAIN

Verification Code Resource URI*

/2fa/cancel

Supported Operations

HTTP Method: POST: Cancel the code that was sent through SMS/ Call/ Email to the destination

Request Parameters

Parameter Description

requestId (Required)

The requestID was received when initiating OTP message.

accountSid (Optional)

If OTP message was initiated on behalf on accountSid, it requires to have same accountSid to be able to cancel the OTP request.

Response

Responde Body Description

code

Sub error code for the request.

message

Message for describing sub error code.

requestID

The unique OTP request identifier for the OTP request.

Response Parameters

cancel API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return

Error Code HTTP Status Error Message Description Category

490

404

Invalid OTP Unique Id

Control (Cancel for now, but may be other too in future) is called for UniqueID which is not present in-system

Control

Example:

{
    "requestId":"XXXXXX" // the requestID received when initiating OTP request.
    "accountSid": "XXXXX"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://$DOMAIN/2fa/cancel \
  --user  ' \{your_account_SID}:\{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId" : "OTPabc2128918293123413216549879",
    "accountSid": "AC123461724187287abcbas791282cf"
}

If cancel is successful, you should see below response

{"code":200,"message":"canceled","requestID":"OTPabc2128918293123413216549879"}

Session Detail Record (SDR)

Session Detail Record API allows to retrieve specific or list of OTP session and its corresponding details like which channel was used to send OTP and underlying error if channel successfully delivered OTP to end user or if there was any error. It also allows to filter based on certain criterias.

Other very important functionality exposed by SDR is Usage Report that allows to retrieve the usage of 2FA for specific period. It also allows to pass specific filter criterias.

Get list of One-Time Passwords - API Reference

Base Resource URI

https://$DOMAIN

Verification Code Resource URI

/2fa/search

Supported Operations

HTTP Method: GET or POST: Returns a list of OTP records from the provided AccountSid, subject to the provided paging, filtering and sorting URL query parameters.

Paging

The following paging parameters are supported

Query Parameter Description

page

Which page of OTP records to return, starting from 0.

pageSize

Number of records returned per page.

Filtering

The following filtering parameters are supported

Query Parameter Description

accountSid

Only include OTP list that is initiated by this specific accountSid. The accountSid should be of one of the sub account’s of this account.

subAccounts

If set to true, include OTP list that is initiated by all the sub accounts within this account. By default false.

service

Only include OTP list that match this service text, partially or fully in any position.
For example if OTP Service is “Support” and service filter parameter is “ppo”, it will match.

channel

Only include OTP list that is initiated via this channel. Possible values are
* call
* sms
* email

from

Only include OTP list that has from begins with this number/email text.

For example if OTP from is “15713316943” and from filter parameter is “1”, it will match. However if from filter parameter is “3”, this record will not match.
This allows to filter OTP sent from specific country code.

to

Only include OTP list that has to begins with this number/email text.

For example if OTP to is “16513333367” and to filter parameter is “1”, it will match. However if to filter parameter is “3”, this record will not match.
This allows to filter OTP sent to specific country code.

targetSid

Only include OTP list that match target sid of SMS/ Call/ Email text, partially or fully in any position.

status

Only include OTP list that has this status. Possible values are
* success
* canceled
* expired

startTime

Optional parameter. Only show OTP list that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Optional parameter. Only show OTP list that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

channelStatus

Only include OTP list that match underlying channel status, partially or fully in any position

* For SMS, possible channel status value can be as explained in https://$DOMAIN/docs/api/sms-api.html#_status_description
* For Call, possible values are as explained in “status” property in below link https://$DOMAIN/docs/api/calls-api.html#_calls_attributes

Response Parameters

search API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.

The response returned is JSON body as shown in example below. Each SDR parameters are as explained below

Response Paremeter Description

sid

OTP UniqueId that was returned when send API was called

service

service parameter passed in when send API was called

accountSid

accountSid parameter passed in when send API was called

dateCreated

Date when this OTP requested was initiated

dateUpadtes

Date when this OTP SDR was updated

staus

Status of this OTP request. Possible values are successful, expired or cancelled
* successful : OTP was successfully verified by verify API call
* expired : OTP expired
* cancelled : OTP was cancelled either by calling cancel API or because send API was called to send new OTP while previous one has not yet been verified or expired.

uri

Unique URI that you can call to get only this specific OTP SDR

checks

Number of verfiy API calls that captures additional details like if it was vaild or invalid and timestamp when verify was received by system. It also captures code used by verify API.

events

This captures the events like sms, call or email that was sent to end user. It has all details like sender, recipient, targetSid which is underlying platform CPaaS id. It also exposes channel Error and message if delivery of SMS, Call or email fails.

Sorting

You can use the SortBy GET or POST query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

SortBy Attributes

Response Paremeter Description

DateCreated

Sort by date on which the OTP was created

Service

Sort by service

Status

Sort by status

Example

From the bash terminal you can run the command below:

  curl -X GET \
    https://$DOMAIN/2fa/search \
    --user  ' \{your_account_SID}:\{your_account_token}' \
    -d '{  "pageSize": "2", "page":"0", "status":"success", "sortBy":"DateCreated:asc"}'

Example response:

{
   "page":0,
   "num_pages":3,
   "page_size":2,
   "total":6,
   "start":0,
   "end":1,
   "uri":"/2fa/search",
   "first_page_uri":"/2fa/search?pageSize=2&page=0&accountSid=ACae6e420f425248d6a26948c17a9e2acf&status=success",
   "previous_page_uri":null,
   "next_page_uri":"/2fa/search?pageSize=2&page=1&accountSid=ACae6e420f425248d6a26948c17a9e2acf&status=success",
   "twoFaOtpSdrs":[
      {
         "sid":"OTP2a73130a3c7d492c93d0b1234596f308",
         "service":"2FA",
         "accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
         "dateCreated":"2019-08-20 10:28:08",
         "dateUpdated":"2019-08-20 10:28:49",
         "status":"success",
         "uri":"/2fa/search/OTP2a73130a3c7d492c93d0b1234596f308",
         "checks":[
            {
               "sid":"OTC2c58e792946b4fc389d7711cafaa5e83",
               "dateReceived":"2019-08-20 10:28:49",
               "status":"valid",
               "code":"312209"
            }
         ],
         "events":[
            {
               "sid":"OTE492b1deb0a7e4a778ab95daa40e7a3f6",
               "dateCreated":"2019-08-20 10:28:08",
               "channel":"email",
               "sender":"info@yourcompany.com",
               "recipient":"jane.doe@yourcompany.com",
               "targetSid":"",
               "channelStatus":"queued"
            }
         ]
      },
      {
         "sid":"OTP02a7c56a08374eedb8789a1a038e7aae",
         "service":"2FA",
         "accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
         "dateCreated":"2019-08-20 02:43:11",
         "dateUpdated":"2019-08-20 02:43:52",
         "status":"success",
         "uri":"/2fa/search/OTP02a7c56a08374eedb8789a1a038e7aae",
         "checks":[
            {
               "sid":"OTC969ccb83b3cf40328c66719039c3b337",
               "dateReceived":"2019-08-20 02:43:31",
               "status":"invalid",
               "code":"847992"
            },
            {
               "sid":"OTC6991f661e3354a6fa1e0393c95168069",
               "dateReceived":"2019-08-20 02:43:52",
               "status":"valid",
               "code":"347469"
            }
         ],
         "events":[
            {
               "sid":"OTEb6f211a28ed0412bb2c097a428d2ad5a",
               "dateCreated":"2019-08-20 02:43:11",
               "channel":"sms",
               "sender":"12012751398",
               "recipient":"919960639901",
               "targetSid":"SM286fa07039ab498d80bd44d4cc91ac3c",
               "channelStatus":"delivered"
            }
         ]
      }
   ]
}

Get single One-Time Passwords - API Reference

Base Resource URI

https://$DOMAIN

Verification Code Resource URI

/2fa/search/{OTPSid}

Supported Operations

HTTP Method: GET: Return OTP session information which is identified by OTP Sid.

Response Parameters

search API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return

Error Code

HTTP Status

Error Message

Description

Category

480

404

Invalid OTP Unique Id

Get single OTP is called for UniqueId which is not present in-system

Get single OTP

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://$DOMAIN/2fa/search/OTPabc2128918293123413216549879 \
  --user  ' \{your_account_SID}:\{your_account_token}'

Example response:

{
    {
        "sid":"OTPe2bd1d6583194aa1aa3892cea1e6d824",
        "service" : "2FA",
        "accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
        "dateCreated":"2019-07-22 04:40:31",
        "dateUpdated":"2019-07-22 04:40:31",
        "status":"expired",
        "uri":"/2fa/search/OTPe2bd1d6583194aa1aa3892cea1e6d824",
        "checks":[],
        "events":[
            {
                "sid":"OTE243d763ffe7747b9a56d395a9e6a7923",
                "dateCreated":"2019-07-22 04:40:31",
                "channel":"sms",
                "sender":"120120105123",
                "recipient":"120120105124",
                "targetSid":"SMd0a8b9819dfa42548bd3c306daade4f3",
                "channelStatus":"undelivered",
            }
        ]
    }
}

Usage record One-Time Passwords - API Reference

The Usage record REST resource provides a simple API to retrieve usage made by your 2FA account during any time period and by any usage channel. This makes it easy to build reporting and analytics tools for your application.

Usage records doesn’t include real time data and can be delayed by maximum of 1 hour.

Base Resource URI

https://$DOMAIN

Verification Code Resource URI

/2fa/usage/records

Supported Operations

HTTP Method: Supports both GET and POST: Return usage record.

Filtering

Usage filter will return usage records for passed filter. Following filtering parameters are supported.

Query Parameter

Description

service

Only include Usage records that match this service text, partially or fully in any position. For example if OTP Service is “Support” and service filter parameter is “ppo”, it will match.

channel

Only include Usage records that is initiated via this channel. Possible values are: call, sms, email

to

Only include Usage records that has to begins with this number/email text. For example if OTP to is “16513333367” and to filter parameter is “1”, it will match. However if to filter parameter is “3”, this record will not match. This allows to filter Usage records sent to specific country code.

status

Only include Usage records that has this status. Possible values are: success, canceled, expired

startTime

Only include Usage records for OTP’s that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

endTime

Only include Usage records for OTP’s that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone.

channelStatus

Only include Usage records that match underlying channel status, partially or fully in any position. For SMS, possible channel status value can be as explained in https://$DOMAIN/docs/api/sms-api.html#_status_description For Call, possible values are as explained in “status” property in below link https://$DOMAIN/docs/api/calls-api.html#_calls_attributes

accountSid

Only include Usage record that is initiated by this specific accountSid. The accountSid should be of one of the sub account’s of this account.

subAccounts

If set to true, include Usage records that is initiated by all the sub accounts within this account. By default false.

Examples

From the bash terminal you can run the command below:

curl -X GET \
  https://$DOMAIN/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z \

Example Response

{
   "usageRecords":[
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-16",
         "endTime":"2020-03-19",
         "count":10,
         "successful":5,
         "unsuccessful":5,
         "unit":"2FA",
         "uri":"/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
      }
   ]
}

HTTP POST example

curl -X POST \
  https://$DOMAIN/2fa/usage/records \
    --user  ' \{your_account_SID}:\{your_account_token}'
    -H 'Cache-Control: no-cache' \
    -H 'Content-Type: application/json' \
    -d '{
      "startTime" : "2020-03-16T18:30:00.000Z",
      "endTime": "2020-03-19"
    }'

Example Response

{
   "usageRecords":[
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-16",
         "endTime":"2020-03-19",
         "count":10,
         "successful":5,
         "unsuccessful":5,
         "unit":"2FA",
         "uri":"/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
      }
   ]
}

Example for SMS filter parameter

HTTP POST example

curl -X POST \
  https://$DOMAIN/2fa/usage/records \
    --user  ' \{your_account_SID}:\{your_account_token}'
    -H 'Cache-Control: no-cache' \
    -H 'Content-Type: application/json' \
    -d '{
      "channel" : "sms"
  }'

Example Response

{
   "usageRecords":[
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-16",
         "endTime":"2020-03-19",
         "count":3,
         "successful":1,
         "unsuccessful":2,
         "unit":"2FA",
         "uri":"/2fa/usage/records?channel=sms&startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
      }
   ]
}

Request Sub resource

The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:

/2fa/usage/records/{Subresource}

Supported subresources are

Subresource Description

Daily

Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved.

Monthly

Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved

Yearly

Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved.

Today

Return Usage record on today.

Yesterday

Return Usage record on yesterday.

ThisMonth

Return Usage record on this month.

LastMonth

Return Usage record on last month.

Filters mentioned in above section can also be passed.

Examples

HTTP GET Example

curl -X GET \
  https://$DOMAIN/2fa/usage/records/daily \
  --user  ' \{your_account_SID}:\{your_account_token}'

Example Response

{
   "usageRecords":[
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-17",
         "endTime":"2020-03-17",
         "count":259200,
         "successful":155671,
         "unsuccessful":103529,
         "unit":"2FA"
      },
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-19",
         "endTime":"2020-03-19",
         "count":140404,
         "successful":84220,
         "unsuccessful":56184,
         "unit":"2FA"
      },
      {
         "description":"2FA Usage record",
         "startTime":"2020-03-18",
         "endTime":"2020-03-18",
         "count":259200,
         "successful":155656,
         "unsuccessful":103544,
         "unit":"2FA"
      }
   ]
}

You can also test your service using Postman or any other alike client.

Common Response Error Code

Response Parameters

Below table shows Error Codes and corresponding HTTP Response across all API calls for 2FA

Error Code

HTTP Status

Error Message

Description

Category

401

401

Validation failed

If validation failed for provided accountSid and token

All

450

401

AccountSid passed is wrong or not sub-account of account “zzzzz”.

“zzzzz” is accountSid passed in validation request, but is wrong or not sub-account of accountSid passed in authentication header.

All

451

400

Mandatory parameter xxx is missing.

xxx is actual parameter name. Comma separated parameters name if multiple.

All

452

400

Underlying message from CPaaS

Error returned by underlying CPaaS platform.

All