Smart 2FA

Overview

Smart 2FA API lets you to send One Time Password (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:

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 the Say-RCML documentation.

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.

limits (Optional)

Key-Value pair Limits to restrict on number of OTPs generated based on criteria that developers select. For further details please look at Limit section.

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 Errors 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

497

409

Invalid Limits. There is no Limits with name "XXX"

Send API is called with Limits name that is not defined.

Send API

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

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 is 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

Limit

Limits provide the capability to enforce limitations on the number of OTPs sent based on various Keys defined. Keys can be defined to put limits based on many parameters. Some of the examples are below

  • Phone Number

  • End User IP Address

  • Application specific Session-Id

  • Geolocation of End User IP Address

This enables developers to safeguard against malicious attacks like bots trying to sign in to an application from one specific IP address or some user intentionally trying to generate many OTPs.

2FA provides flexibility for Developers to define Limits based on mixed Keys. For example 1 OTP per min per number but 4 OTP per min per IP address etc.

Each Limit has, Buckets associated with (maximum of 2 Buckets allowed per Limit) to put restrictions for that Limit. For example 1 OTP per 60 Seconds and 10 OTP per 86400 Seconds (24 Hrs) for Limit based on Phone Number. Which means OTP will be limited to 1 per min and maximum 10 per day for the same Phone Number recipient.

Developers have to pass a list of Limits when invoking Send API to enforce limits.

If no Limit is defined by Developer or if no Limit is passed when invoking Send API, by default 1 OTP per min per recipient phone number will be applied as default.

Order of Limit in Send API

If Developer is calling the Send API with a combination of “limits“ as explained in Request Parameters of Send, the order of limits defined matters.

For example consider below two limits defined.

  • “limit_on_Session“ with only one bucket [ {"name":"bucket1", "max":"1", "interval":"60"}]

  • “limit_on_phonenumber“ with two buckets [{"name":"bucket1","max":"1", "interval":"30"},{ "name":"bucket2", "max":"2", "interval":"300"}]

Example 1

Developer calls send API passing below parameter with given order.

"limits" : "{ \"limit_on_Session\":\"aabbcd\", \"limit_on_phonenumber\": \"919960639903\" }"

  • timestamp “T0“: 1st Send API called. OTP will be sent.

  • timestamp “T1=T0+31 sec“: 2nd Send API called. OTP will be blocked with error code 454 and error message “Too many Otp requests to the same Limit! key: limit_on_Session with value: aabbcd“

  • timestamp “T2=T0+61 sec“: 3rd Send API called. OTP will be sent.

  • From T2 to “T0+300 sec“ OTP will be blocked

Example 2

Developer calls send API passing below parameter with given order

"limits" : "{ \"limit_on_phonenumber\": \"919960639903\",\"limit_on_Session\":\"aabbcd\" }"

  • timestamp “T0“: 1st Send API called. OTP will be sent.

  • timestamp “T1=T0+31 sec“: 2nd Send API called. OTP will be sent.

  • timestamp “T2=T0+61 sec“: 3rd Send API called. OTP will be blocked

  • From T2 to “T0+300 sec“ OTP will be blocked.

Create Limit

The create Limit endpoint API is called to create a new Limit for a given Account.

Base Resource URI

https://$DOMAIN

Create Limit Resource URI

/2fa/limits

Supported Operations

HTTP POST: Create Limit

Request Parameters

Parameter Description

name

Mandatory. Unique Name for this Limit. Developers will pass this as key when passing Limit to Send API.

buckets

JSON body of Buckets. For example

"buckets":[ { "name":"bucket1", "max":"1", "interval":"10" }, { "name":"bucket2", "max":"10", "interval":"86400" } ]

Note interval is in seconds.

description

Optional. Description for this Limit

accountSid

Optional. Sub-Account Sid for which Limit is to be created. If not passed Limit is created for same Account calling the API

Response Body

The Response Body will carry Code, corresponding message and data of Limit if it was successfully created. HTTP response will be 200 OK.

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

Parameter Description

code

Sub-error code in case of error

message

Message describing error if error occured or success message

data

Limit data as explained in the table below.
Limit Data Parameter
Data Parameter Description

sid

Unique Limit Id

accountSid

Unique CPaaS Account wich called API to create the Limit

accountEmail

Unique CPaaS Account email corresponding to accountSid

targetAccountSid

Unique CPaaS Account for which this particular Limit is created

targetAccountEmail

Unique CPaaS Account email corresponding to targetAccountSid

dateCreated

Timestamp when this Limit was created.

dateUpdated

Timestamp when this Limit was updated

name

Unique Name of this Limit

buckets

JSON formatted Buckets as explained below:

- name: Any descriptive name that makes sense
- max: Maximum Otp allowed for given interval in seconds
- interval: Time period in seconds to throttle send OTP requests.

description

Description for this Limit

uri

Unique URI that you can call to get only this specific Enterprise

Create Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code

HTTP Status

Error Message

Description

Category

492

409

Limit with that Name already exists

Limit name should be unique in given Account

Create Limit

Example

{
    "name" : "limit_on_phoneNumber",
    "description" : "Limit number of OTP sent per recipient Phone Number",
   "buckets":[
      {
         "name":"Min bucket",
         "max":"1",
         "interval":"10"
      },
      {
         "name":"Max bucket",
         "max":"10",
         "interval":"86400"
      }
   ]
 }

From the bash terminal you can run the command below:

curl -X POST \
  https://your_custom_domain/2fa/limits \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "limit_on_phonenumber",
    "buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
    "description": "limit on Phone Number"
}'

If creation of limit is successful, below is the response returned:

{
    "data": {
        "sid": "LMe7d332c72d2f40b9bfe8982425af14bc",
        "name": "limit_on_phonenumber",
        "buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
        "description": "limit on Phone Number",
        "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
        "uri": "/2fa/limits/search/LMe7d332c72d2f40b9bfe8982425af14bc"
    },
    "code": 200,
    "message": "OK"
}

If creation of Limit fails, below response is returned with corresponding HTTP Error Code

{
    "code": 492,
    "message": "Limit with that Name already exists",
    "requestID": null
}

Update Limit

The update Limit endpoint API is called to update existing Limit for a given Account.

Updated in Bucket value will be reflected in maximum 5 mins as System caches the Buckets to avoid frequent round-trip to database.

Base Resource URI

https://$DOMAIN

Update Limit Resource URI

/2fa/limits/{limitSid}

Supported Operations

HTTP PUT: Update Limit

Request Parameters

Parameter

Description

limitSid

Mandatory. Unique SID of limit that was returned when Create Limit was invoked.

buckets

Optional. JSON formatted Buckets as explained below

name: Any descriptive name that makes sense
max: Maximum Otp allowed for given interval in seconds
interval: Time period in seconds to throttle send OTP requests.

description

Optional. Description for this Limit
Account can update Sub-Account Limits

Response Body

The Response Body will carry Code, corresponding message and data of Limit if it was successfully created. HTTP response will be 200 OK.

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

Parameter

Description

code

Sub-error code in case of error

message

Message describing error if error occured or success message

data

Limit data as explained in the table.

Update Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code

HTTP Status

Error Message

Description

Category

493

409

Invalid Limit Id

Limit sid passed is not present in the System

Update, Search Single, Delete Limit

Example:

{
       "description" : "Limit number of OTP sent per recipient Phone Number. Pass with Send API",
"buckets":[
      {
         "name":"Min bucket",
         "max":"2",
         "interval":"10"
      },
      {
         "name":"Max bucket",
         "max":"20",
         "interval":"86400"
      }
 	]
 }

From the bash terminal you can run the command below:

curl -X PUT \
  https://your_custom_domain/2fa/limits/LM88170d5b0e1f4eb3ad724ffc8131c9c1 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "buckets":"[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
    "description": "limit on Phone Number of receiver blabla"
}'

If update of limit is successful, below is the response returned:

{
    "data": {
        "sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
        "name": "limit_on_Session",
        "buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
        "description": "limit on Phone Number of receiver blabla",
        "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
        "uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
    },
    "code": 200,
    "message": "OK"
}

If update of Limit fails, below response is returned with corresponding HTTP Error Code

{
    "code": 493,
    "message": "Invalid Limit Id",
    "requestID": null
}

Delete Limit

The delete Limit endpoint API is called to delete existing Limit for a given Account.

Base Resource URI

https://$DOMAIN

Delete Limit Resource URI

/2fa/limits/{limitSid}

Supported Operations

HTTP DELETE: Delete Limit

Request Parameters

Parameter

Description

limitSid

Mandatory. Unique SID of limit that was returned when Create Limit was invoked.
Account can Delete SubAccount Limits

Response Body

The Response Body will carry Code, corresponding message and data of Limit if it was successfully deleted. HTTP response will be 200 OK.

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

Parameter

Description

code

Sub-error code in case of error

message

Message describing error if error occured or success message

data

Limit data as explained in the table.

Delete Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return

Error Code

HTTP Status

Error Message

Description

Category

493

409

Invalid Limit Id

Limit sid passed is not present in the System

Update, Search Single, Delete Limit, Create Bucket

Example:

From the bash terminal you can run the command below:

curl -X DELETE \
  https://your_custom_domain.com/2fa/limits/LM4d9cfa53230848199d787a99f1b431a4 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If delete of limit is successful, below is the response returned:

{
    "data": {
        "sid": "LM4d9cfa53230848199d787a99f1b431a4",
        "name": "limit_on_IP",
        "buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
        "description": "limit on IP",
        "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
        "uri": "/2fa/limits/search/LM4d9cfa53230848199d787a99f1b431a4"
    },
    "code": 200,
    "message": "OK"
}

If delete of Limit fails, below response is returned with corresponding HTTP Error Code

{
    "code": 493,
    "message": "Invalid Limit Id",
    "requestID": null
}

Get list of Limits

List Limits API allows users to list all the Limits created under that “Account“ or “Sub-Account“

Base Resource URI

https://$DOMAIN

Get List of Limits Resource URI

/2fa/limits/search

Supported Operations

HTTP GET: List Limits

Paging

The following paging parameters are supported

Query Parameter

Description

page

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

pageSize

Number of records returned per page
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call.

Filtering

Following filtering parameters are supported

Query Parameter

Description

name

Optional parameter. Only show Limits that match name text, partially or fully.

accountSid

Only include Limits list that is initiated by this specific accountSid. The accountSid should be one of the sub accounts of this account.

subAccounts

If set to true, include Limits that are associated to all the sub accounts within this account. By default false.

startTime

Optional parameter. Only show limits 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 Limits 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.

Sorting Information

You can use the SortBy GET 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 is the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of Limits is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:

Sort Attributes

Parameter

Description

name

Sort by name

dateCreated

Sort by date when Limit was created

Response Parameters

Search Limit 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 the example below. Each parameters are as explained below

Code

Description

code

Sub-error code for response

message

Message describing error if error occured or success message

data

List of Limits data of search as explained in table below
Data parameters

Data Parameter

Description

result

Limits data as explained in the table 6.1.5.1 Limit Data Parameter.

pageSize

Number of records returned per page.

total

Total Number of records

page

Which page of records to return.

numPages

Total number of pages

start

Starting offset of page

end

Ending offset of page

firstPageUri

Unique URI that you can call to get records in First page

nextPageUri

Unique URI that you can call to get records in next page

uri

Unique URI that you can call to get records

Example:

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain.com/2fa/limits/search?pageSize=2&page=0 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "result": [
            {
                "sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
                "name": "limit_on_Session",
                "buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
                "description": "limit on Phone Number of receiver blabla",
                "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
                "uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
            },
            {
                "sid": "LMe7d332c72d2f40b9bfe8982425af14bc",
                "name": "limit_on_phonenumber",
                "buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
                "description": "limit on Phone Number",
                "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
                "uri": "/2fa/limits/search/LMe7d332c72d2f40b9bfe8982425af14bc"
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/2falimits/search/?pageSize=10&page=0",
        "uri": "/2falimits/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Limits

Single Limits search API allows users to retrieve specific Limits created under that “Account“ or “Sub-Account“

Base Resource URI

https://$DOMAIN

Get Single Limits Resource URI

/2fa/limits/search/{LimitSid}

Supported Operations

HTTP GET: Specific Limits

Request Parameters

Parameter

Description

limitSid

Mandatory. Unique SID of limit that was returned when Create Limit was invoked.
Account can get single Limits of SubAccount

Response Parameters

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

Error Code

HTTP Status

Error Message

Description

Category

493

409

Invalid Limit Id

Limit sid passed is not present in the System

Update, Search Single, Delete Limit

Example:

From the bash terminal you can run the command below:

curl -X GET \
  https://your_custom_domain/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
        "name": "limit_on_Session",
        "buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
        "description": "limit on Phone Number of receiver blabla",
        "accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
        "uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
    },
    "code": 200,
    "message": "OK"
}