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.
How 2FA Works?
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
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.
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 |
495 |
409 |
Invalid Limit 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"}
Example of sending OTP with limits:
curl -X POST \
https://yourdomain.com/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}",
"limits" : { "limit_on_phone": "+1205XXXXXXX" }
}'
Verify
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.
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. For backward compatibility, this is mandatory if the API is called by passing the |
requestId |
The requestID was received when initiating the OTP message. This parameter can be ignored if the service and number attributes are being used. It is also not needed if using the |
number |
The phone number to which the SMS containing the verification code was sent to. Not needed if you are using verify via |
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 |
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 OTP.
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 |
471 |
409 |
OTP is already verified |
Cancel is called for UniqueId which is present in-system but already verified successfully |
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
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. |
channel |
Only include OTP list that is initiated via this channel. Possible values are - call |
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. |
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. |
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 |
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 |
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 |
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}'
Example response:
{
"page": 0,
"num_pages": 1,
"page_size": 10,
"total": 1,
"start": 0,
"end": 0,
"uri": "/2fa/search/?pageSize=10&page=0",
"first_page_uri": "/2fa/search/?pageSize=10&page=0",
"previous_page_uri": null,
"next_page_uri": null,
"twoFaOtpSdrs": [
{
"sid": "OTP233b636452e14782b63df062ab467f8f",
"service": "2FA",
"accountSid": "ACc6588005a608439e69889c45511defd6",
"organizationSid": "ORafbe225ad37541eba518a74248f0ac4c",
"code": "601817",
"dateCreated": "2021-02-02T16:04:04.000+0000",
"dateUpdated": "2021-02-02T16:04:05.000+0000",
"status": "expired",
"checks": [],
"events": [
{
"sid": "OTE7ae7d6d28e744262b4983cdb961bd8a8",
"dateCreated": "2021-02-02T16:04:04+0000",
"dateUpdated": "2021-02-02T16:04:04+0000",
"channel": "sms",
"sender": "12224445555",
"recipient": "13334748363",
"targetSid": "SM3769217bf2fc4b7ea22ad5502bfa492c",
"channelStatus": "undelivered",
"channelErrorCode": "30008"
}
]
}
]
}
Get single One-Time Passwords - API Reference
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": "OTP233b636452e14782b63df062ab467f8f",
"service": "2FA",
"accountSid": "ACc6588005a608439e69889c45511defd6",
"organizationSid": "ORafbe225ad37541eba518a74248f0ac4c",
"code": "601817",
"uri": "/2fa/seach/OTP233b636452e14782b63df062ab467f8f?accountSid=ACc6588005a608439e69889c45511defd6",
"dateCreated": "2021-02-02T16:04:04.000+0000",
"dateUpdated": "2021-02-02T16:04:05.000+0000",
"status": "expired",
"checks": [],
"events": [
{
"sid": "OTE7ae7d6d28e744262b4983cdb961bd8a8",
"dateCreated": "2021-02-02T16:04:04+0000",
"dateUpdated": "2021-02-02T16:04:04+0000",
"channel": "sms",
"sender": "12224445555",
"recipient": "13334748363",
"targetSid": "SM3769217bf2fc4b7ea22ad5502bfa492c",
"channelStatus": "undelivered",
"channelErrorCode": "30008"
},
null
]
}
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. |
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 of OTP Usage
From the bash terminal you can run the command below:
curl -X GET \
https://$DOMAIN/2fa/usage/records?startDate=2019-07-01&endDate=2021-02-02 \
Example Response
{
"usageRecords": [
{
"description": "2FA Usage record",
"accountSid": "ACc6588005a608439e69889c45511defd6",
"count": 41,
"successful": 12,
"unsuccessful": 29,
"unit": "2FA",
"uri": "/2fa/usage/records?endDate=2021-02-02&startDate=2019-07-01"
}
]
}
Example of Call Usage
From the bash terminal you can run the command below:
curl -X GET \ https://yourdomain.com/2fa/usage/records?channel=call&startDate=2019-07-01&endDate=2020-07-23
\
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"usageRecords": [
{
"description": "2FA Usage record",
"accountSid": "ACc6588005a608439e69889c45511defd6",
"count": 16,
"successful": 7,
"unsuccessful": 9,
"unit": "2FA",
"uri": "/2fa/usage/records?channel=call&endDate=2020-07-23&startDate=2019-07-01"
}
]
}
Example of SMS Usage
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/2fa/usage/records.json?channel=sms&startDate=2019-07-01&endDate=2020-07-23 \
-u 'YourAccountSid:YourAuthToken'
Below is the response returned:
{
"usageRecords": [
{
"description": "2FA Usage record",
"accountSid": "ACc6588005a608439e69889c45511defd6",
"count": 18,
"successful": 1,
"unsuccessful": 17,
"unit": "2FA",
"uri": "/2fa/usage/records?channel=sms&endDate=2020-07-23&startDate=2019-07-01"
}
]
}
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
From the bash terminal you can run the command below:
curl -X GET \
https://$DOMAIN/2fa/usage/records/daily \
--user ' \{your_account_SID}:\{your_account_token}'
Example Response
{
"usageRecords": [
{
"description": "2FA Usage record",
"startTime": "2021-02-01",
"endTime": "2021-02-01",
"count": 4,
"successful": 0,
"unsuccessful": 4,
"unit": "2FA"
}
]
}
In the above example if you don’t pass startDate and endDate parameters, 30 records will be shown.
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.
Base Resource URI
https://$DOMAIN
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 |
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": "LM29c3cdc8123545a4aa62b7451f1f719d",
"name": "limit_on_phoneNumber",
"buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "Limit number of OTP sent per recipient Phone Number",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "jane@company.com",
"targetAccountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"targetAccountEmail": "alice@company.com",
"uri": "/2fa/limits/search/LM29c3cdc8123545a4aa62b7451f1f719d",
"dateCreated": "2021-02-04T03:52:09.400+0000",
"dateUpdated": "2021-02-04T03:52:09.400+0000"
},
"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. |
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 |
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/LMcd3f402bbbf44bda858e3ab8f9bd5d44 \
--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": "LMcd3f402bbbf44bda858e3ab8f9bd5d44",
"name": "limit_on_phoneNumberr",
"buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver blabla",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "jane@company.com",
"targetAccountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"targetAccountEmail": "alice@company.com",
"uri": "/2fa/limits/search/LMcd3f402bbbf44bda858e3ab8f9bd5d44",
"dateCreated": "2021-02-04T03:55:02.000+0000",
"dateUpdated": "2021-02-04T03:56:12.122+0000"
},
"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.
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/LMcd3f402bbbf44bda858e3ab8f9bd5d44 \
--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": "LMcd3f402bbbf44bda858e3ab8f9bd5d44",
"name": "limit_on_phoneNumberr",
"buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "alice@company.com",
"targetAccountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"targetAccountEmail": "jane@company.com",
"uri": "/2fa/limits/search/LMcd3f402bbbf44bda858e3ab8f9bd5d44",
"dateCreated": "2021-02-04T03:55:02.000+0000",
"dateUpdated": "2021-02-04T03:56:12.000+0000"
},
"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“
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:
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": "LMec2561784a7f425e8049c8c27d4250db",
"name": "limit_on_phone",
"buckets": "[{\"name\":\"bucket1\",\"max\":\"1\",\"interval\":\"60\"},{\"name\":\"bucket2\",\"max\":\"2\",\"interval\":\"300\"}]",
"description": "Set limit on destination phone number to have maximum 1 OTP per min and maximum 2 per 5 mins",
"accountSid": "ACdcd5c6fe672b241945f495c4ca1a4966",
"accountEmail": "jane@company.com",
"targetAccountSid": "ACdcd5c6fe672b241945f495c4ca1a4966",
"targetAccountEmail": "alice@company.com",
"uri": "/2fa/limits/search/LMec2561784a7f425e8049c8c27d4250db",
"dateCreated": "2020-04-10T00:33:53.000+0000",
"dateUpdated": "2020-07-30T13:25:22.000+0000"
},
{
"sid": "LMfddc80d59f3549dd9044950e5c0ca7c6",
"name": "test",
"buckets": "[{\"name\":\"bucket1\",\"max\":\"1\",\"interval\":\"20\"}]",
"description": "tesr",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "jane@company.com",
"targetAccountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"targetAccountEmail": "alice@company.com",
"uri": "/2fa/limits/search/LMfddc80d59f3549dd9044950e5c0ca7c6",
"dateCreated": "2020-12-18T03:29:18.000+0000",
"dateUpdated": "2020-12-18T03:29:18.000+0000"
}
],
"pageSize": 2,
"total": 7,
"page": 0,
"numPages": 4,
"start": 0,
"end": 1,
"firstPageUri": "/2falimits/search/?pageSize=2&page=0",
"nextPageUri": "/2falimits/search/?pageSize=2&page=1",
"uri": "/2falimits/search/?pageSize=2&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“
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/LMfddc80d59f3549dd9044950e5c0ca7c6 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "LMfddc80d59f3549dd9044950e5c0ca7c6",
"name": "test",
"buckets": "[{\"name\":\"bucket1\",\"max\":\"1\",\"interval\":\"20\"}]",
"description": "tesr",
"accountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"accountEmail": "jane@company.com",
"targetAccountSid": "AC55a9977a50647d2fa38fa1f505206aaf",
"targetAccountEmail": "alice@company.com",
"uri": "/2fa/limits/search/LMfddc80d59f3549dd9044950e5c0ca7c6",
"dateCreated": "2020-12-18T03:29:18.000+0000",
"dateUpdated": "2020-12-18T03:29:18.000+0000"
},
"code": 200,
"message": "OK"
}