Headless - OTP - OTPLESS

Prerequisites

Make sure you have followed the SDK Setup Guide before starting with this document.
Ensure you have admin access to the OTPless Account.

Configure OTP Auth on Dashboard

Log in to the OTPless dashboard with your registered email ID.
Go to Configure Channel.
Enable the phone or email channel based on your requirement.
When you enable the channel, you will see the option to configure the auth method and delivery channel.
Choose OTP as the auth method.

Important: Don’t forget to save and publish the configuration.

Choose your Programming Language:

Step 1: Send OTP

Choose your identity type to verify:

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("YOUR_COUNTRY_CODE","YOUR_PHONE_NUMBER");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("YOUR_COUNTRY_CODE","YOUR_PHONE_NUMBER");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for email verification, set the email address for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setEmail("YOUR_EMAIL_ID");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "EMAIL",
    "deliveryChannel": "EMAIL",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the email address and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setEmail("EMAIL_INPUT");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "EMAIL"
  }
}

Step 1: Send OTP

Choose your identity type to verify:

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("YOUR_COUNTRY_CODE","YOUR_PHONE_NUMBER");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("YOUR_COUNTRY_CODE","YOUR_PHONE_NUMBER");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for email verification, set the email address for the OTP request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setEmail("YOUR_EMAIL_ID");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "EMAIL",
    "deliveryChannel": "EMAIL",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the email address and OTP for the verification request.

Request

final HeadlessRequest request = new HeadlessRequest();
request.setEmail("EMAIL_INPUT");
request.setOtp("XXXXXX");
otplessView.startHeadless(request, this::onHeadlessCallback);

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "EMAIL"
  }
}

Step 1: Send OTP

Choose your identity type to verify:

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request. Request

val request = HeadlessRequest()
request.setPhoneNumber("YOUR_COUNTRY_CODE", "YOUR_PHONE_NUMBER")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success

": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

val request = HeadlessRequest()
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER")
request.setOtp("XXXXXX")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for phone number verification, set the phone number and country code for the OTP request. Request

val request = HeadlessRequest()
request.setPhoneNumber("YOUR_COUNTRY_CODE", "YOUR_PHONE_NUMBER")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success

": true,
  "response": {
    "channel": "PHONE",
    "deliveryChannel": "WHATSAPP",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the phone number, country code, and OTP for the verification request.

Request

val request = HeadlessRequest()
request.setPhoneNumber("PHONE_COUNTRY_CODE", "INPUT_PHONE_NUMBER")
request.setOtp("XXXXXX")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "PHONE"
  }
}

To initiate an OTP for email verification, set the email address for the OTP request. Request

val request = HeadlessRequest()
request.setEmail("YOUR_EMAIL_ID")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "channel": "EMAIL",
    "deliveryChannel": "EMAIL",
    "authType": "OTP",
    "requestId": "xxxxxxxxxxxxxxxx"
  }
}

Step 2: Verify OTP

To verify the OTP entered by the user, set the email address and OTP for the verification request.

Request

val request = HeadlessRequest()
request.setEmail("EMAIL_INPUT")
request.setOtp("XXXXXX")
otplessView.startHeadless(request, this::onHeadlessCallback)

Response

{
  "statusCode": 200,
  "success": true,
  "response": {
    "verification": "COMPLETED",
    "requestId": "xxxxxxxxxxxxxxxx",
    "channel": "EMAIL"
  }
}

Step 3: Get Auth Token

Awesome! You’ve completed the client-side integration. Now, after the OTP is verified, you’ll get a callback with the ONETAP response containing the token. You’ll need to parse the token from the response JSON.

Sample Callback JSON

{
  "responseType": "ONETAP",
  "statusCode": 200,
  "response": {
    "status": "SUCCESS",
    "token": "unique_token_here",
    "userId": "unique_user_id_here",
    "timestamp": "ISO_timestamp_here",
    "identities": [
      {
        "identityType": "MOBILE",
        "identityValue": "919899038845",
        "channel": "OTP",
        "methods": [
          "SMS"
        ],
        "verified": true,
        "verifiedAt": "2024-08-05T13:57:56Z"
      }
    ],
    "idToken": "jwt_token",
    "network": {
      "ip": "127.0.0.1",
      "timezone": "Asia/Kolkata",
      "ipLocation": {}
    },
    "deviceInfo":{},
    "sessionInfo":{},
    "firebaseInfo":{}
  }
}

You can view a complete sample response here

How to parse the token from response?

private void onHeadlessCallback(HeadlessResponse response) {
    if (response.getStatusCode() == 200) {
        switch (response.getResponseType()) {
            case "ONETAP":
                // final response with token
                JSONObject responseWithToken = response.getResponse();
                // Your API to send the token to your backend and then follow the next step.
                break;
            // other response types
        }
        JSONObject successResponse = response.getResponse();
    } else {
        // handle error
        String error = response.getResponse().optString("errorMessage");
    }
}

🏁 Check Point : Verify Auth Token

Once you have retrieved the token, send it to your backend and call the verify token API.

Verify Token API →

Plugins

Web SDKs

Native/Mobile SDKs

References

Headless - OTP

Prerequisites

Configure OTP Auth on Dashboard

Choose your Programming Language:

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 3: Get Auth Token

🏁 Check Point : Verify Auth Token

Plugins

Web SDKs

Native/Mobile SDKs

References

​Prerequisites

​Configure OTP Auth on Dashboard

​Choose your Programming Language:

​Step 1: Send OTP

​Choose your identity type to verify:

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 1: Send OTP

​Choose your identity type to verify:

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 1: Send OTP

​Choose your identity type to verify:

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 2: Verify OTP

​Step 3: Get Auth Token

​🏁 Check Point : Verify Auth Token

Prerequisites

Configure OTP Auth on Dashboard

Choose your Programming Language:

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 1: Send OTP

Choose your identity type to verify:

Step 2: Verify OTP

Step 2: Verify OTP

Step 2: Verify OTP

Step 3: Get Auth Token

🏁 Check Point : Verify Auth Token