Two Factor Authentication
Two Factor Authentication, also known as 2FA, is the dynamic generation of a numeric/alphanumeric/alphabetical
code that authenticates the user for a single transaction or session. The code or one-time password (OTP) can be
sent to the customer via SMS.
Pre-start checklist
- User name & password. If you don’t have an account, you can create one at Gupshup Enterprise SMS.
- For 2FA Account configuration please share the details as mentioned in the table with the support team.
| Parameters | Description |
|---|---|
| Enterprise Account ID | Numeric Account Id |
| OTP Expiry in Seconds | Expiry time of an OTP for an enterprise user |
| OTP Retry in Seconds | Number of seconds an enterprise user has to wait before the user can resend an OTP |
| Allowed OTP Verification Attempts | Number of attempts allowed to verify an OTP |
Parameters
| Parameter | Value | Description |
|---|---|---|
| userid | Account number provided by Enterprise SMS GupShup | The number must be in pure numeric format with no special characters. |
| password | UrlEncoded string of UTF-8 characters | Password provided by Gupshup for authentication of user ID. The password must be the same as used to log on to the Enterprise SMS GupShup website. |
| method | TWO_FACTOR_AUTH | Method for performing a specific action. |
| v | 1.1 | The default version is 1.1, unless otherwise specified. |
| Phone_no | Phone no. of the receiver | The number must be in pure numeric format with no special characters |
| msg | UrlEncoded string of UTF-8 characters | The message that needs to be sent. It can contain alphanumeric & special characters. The message must contain %code% |
| msg_type | Text or Unicode_text | Indicates the type of the message to be sent. Default is “text”. |
| format | TEXT, XML, JSON | Specific format for response message |
| otpCodeLength | Numeric | This is the length of an OTP. It must be a positive integer less than or equals to 10. |
| otpCodeType | NUMERIC, ALPHABETIC or ALPHANUMERIC | This parameter specifies the type of an OTP. 3 values are permitted NUMERIC (only numbers), ALPHABETIC (only alphabets), ALPHANUMERIC (mix of numbers and alphabets). |
| otp_code | OTP to be verified | The API verifies OTP if given otherwise sends OTP (This is the only difference between Send OTP and Verify OTP). |
Generate and send OTP
Sample API request
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=XXXXXXXX&password=XXXXX&method=
TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXXX&msg=
Your%20OTP%20code%20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC
Response Message
success | 919XXXXXXXXX | 3545912456442574189 | OTP sent
Verify OTP
Sample API request
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=XXXXXXX&password=XXXXXX&
method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX& otp_code=1564
Response Message
success | 919XXXXXXXXX | 3545913275288024429 | OTP matched
Encrypted payload for Two Factor Authentication API call
Steps for Encryption
- Form a querystring using the rest of API parameters and its values.
Example: password=XXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&msg=Y
our%20OTP%20code%20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC. - Encrypt the querystring using the AES encryption algorithm(256 bit algorithm)
- Use only GCM mode
- Length of IV (Initialization Vector) parameter should be 12 bytes. IV value should be unique for every API
request/call. - Length of authentication tag should be 16 bytes
- Output of AES Encryption (256 bit) should be encoded using base 64 Urlsafe.
- The Base64 encoded encrypted cipher will be passed as a payload in encrdata parameters.
- Sample of encrypted payload using above steps:
VEYcNxNQQcZ0t6VcfxZwzTpeTmBb0UKPYORWA1_VEIaGWrg7zS6aOdUYvmXCpOZbyGs2w9xKA_c43r0OnrL3KHUgUrvIY1_5eOm8y5zoWyCaWbV2OKFpa5yZQe0GQrm8PZyBJYIDgE7qswrrPj005nZZyFiCtDP50UDnaeg6RTVKV748lkURa1RDcs3lMkh3n5UsaNM5TU_lhkC0yreyuuNu8mlRQmNFDMUMWOfvNvhLL_H4
The following are the required parameters
| Parameter | Description |
|---|---|
| userid | Specify the user id provided by Gupshup. This must be sent in plaintext (unencrypted). The number must be in pure numeric format with no special characters. |
| encrdata | Encrypted parameters and values are sent in query parameters / payload. |
Parameters and values to be passed in encrdata. Please note both the parameter and its value should be
encrypted.
| Parameter | Value | Description |
|---|---|---|
| method | TWO_FACTOR_AUTH | The method for performing a specific action i.e. send an OTP SMS. Parameter and its value must be sent in encrypted format. Encrypted string should be URL encoded before sending it. |
| v | 1.1 | The default version is 1.1 and must be passed. Parameter and its value must be sent in encrypted format. Encrypted string should be URL encoded before sending it. |
| Phone_no | Phone no. of the receiver | The number must be in the pure numeric format with no special characters, and should include the country code and mobile number of the recipient. Parameter and its value must be sent in encrypted format. Encrypted string should be URL encoded before sending it. |
| msg | UrlEncoded string of UTF-8 characters | The message that needs to be sent. It can contain alphanumeric & special characters. The message must contain %code%. Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
| msg_type | Text or Unicode_text | Indicates the type of the message to be sent. The default is “text”. Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
| format | TEXT, XML, JSON | Specific format for API response message. Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
| otpCodeLength | Numeric | This is the length of an OTP. It must be a positive integer less than or equals to 10. Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
| otpCodeType | NUMERIC, ALPHABETIC or ALPHANUMERIC | This parameter specifies a type of OTP. 3 values are permitted NUMERIC (only numbers), ALPHABETIC (only alphabets), ALPHANUMERIC (mix of numbers and alphabets). Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
| otp_code | OTP to be verified | The API verifies OTP if given otherwise sends OTP (This is the only difference between Send OTP and Verify OTP). Parameter and its value must be sent in encrypted format. Encrypted strings should be URL encoded before sending it. |
Sample Request
A sample request for “Generate and Send OTP + Verify OTP API” with encrypted data in the API payload looks like
this.
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata={{Base64 Encoded Encrypted Data}}
Generate and send OTP SMS:
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata=
VEYcNxNQQcZ0t6VcfxZwzTpeTmBb0UKPYORWA1_VEIaGWrg7zS6aOdUYvmXCpOZbyGs2w9xKA_c43r0OnrL3KHUgUr
vIY1_5e-Om8y5zoWyCaWbV2OKFpa5yZQe0GQrm8PZyBJ-YIDgE7qswrrPj005nZZyFiCtDP50UDnaeg6RTVKV748lkURa1RDcs3lMkh3n5UsaNM5TU_lhkC0yreyuuNu8mlRQmNFDMUMWOfvNvhLL_H4
where
encrdata=
{{password=XXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&msg=Your%20OTP%20code%
20is%20%25code%25&format=text&otpCodeLength=4&otpCodeType=NUMERIC}}
Verify OTP API:
https://enterprise.smsgupshup.com/GatewayAPI/rest?userid=xxxxxxxx&encrdata=
2qrYFF2dZpT1kLC9iFlfv2mdJgbtUntUuXtRj_Yz5-tVw3JDUNgvGIBHZFQMtJjNsMQwGEV6WZ3uFQPGdGYeVV43Ah3u82BVGO8naTea_Dbw1WbDd-cwc1uoGN8ip14suC6fEOJE2oz7Gy0
where
encrdata= {{password=XXXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX&otp_code=1564}}
The API response format is the same as the unencrypted payload. The output of encardata will be different every time as the IV (Initialization Vector) value will be unique for every request.
Please note that the “userid” parameter is mandatory and its value is to be sent in unencrypted format. All the other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded using the key.
You must use the key generated for your enterprise account to encrypt API parameter values when sending the API
request. Once the request is received by Gupshup, the payload is decrypted by Gupshup and sent ahead to the operator.
Updated almost 2 years ago
What’s Next