Prerequisites
- Make sure you have followed the SDK Setup Guide before starting with this document.
- Ensure you have admin access to the OTPless Account.
- 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 →