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

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

1. 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.
2. 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

3. Output of AES Encryption (256 bit) should be encoded using base 64 Urlsafe.
4. The Base64 encoded encrypted cipher will be passed as a payload in encrdata parameters.
5. Sample of encrypted payload using above steps:
   VEYcNxNQQcZ0t6VcfxZwzTpeTmBb0UKPYORWA1_VEIaGWrg7zS6aOdUYvmXCpOZbyGs2w9xKA_c43r0OnrL3KHUgUrvIY1_5eOm8y5zoWyCaWbV2OKFpa5yZQe0GQrm8PZyBJYIDgE7qswrrPj005nZZyFiCtDP50UDnaeg6RTVKV748lkURa1RDcs3lMkh3n5UsaNM5TU_lhkC0yreyuuNu8mlRQmNFDMUMWOfvNvhLL_H4

The following are the required parameters

Parameters and values to be passed in encrdata. Please note both the parameter and its value should be
encrypted.

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.