Skip to main content

Requirements

  • The compileSdk version should be 35.
  • The minimum SDK version supported by the SDK is 21.
  • The kotlin version should be 1.9.0 and above.
  • The gradle version should be 8.3.1 and above.
This is the new Headless authentication SDK that is significantly faster and more robust than the previous version. This upgrade enhances performance, reliability, and security, ensuring a seamless authentication experience, along with a seamless integration process. We strongly recommend migrating to the new SDK for improved efficiency and better support. To migrate from the old SDK, remove the previous SDK dependency and integration and follow the below mentioned steps.

​
Overview

OTPless SDK accepts the user’s identity (phone number or email), authenticates through multiple channels, and returns a secure token upon success.The merchant app sends this token to its backend, which verifies it with the OTPless Server before proceeding with the user journey. SDK Overview Chart

​
Integration Steps

​
Step 1: Add SDK Dependency

First, let’s add the OTPLESS SDK to your project. Update your app’s build.gradle file by adding the following dependency: 
  implementation ("io.github.otpless-tech:otpless-headless-sdk:latest_version")
Please check the latest version of the SDK here. Make sure to synchronize your Gradle project to fetch the dependency.

​
Step 2: Update AndroidManifest.xml

Add this intent filter to your LoginActivity in AndroidManifest.xml: 
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.BROWSABLE" />
    <category android:name="android.intent.category.DEFAULT" />
    <data
        android:scheme="otpless.your_appid_in_lowercase"
        android:host="otpless" />
</intent-filter>
Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.
🔍 Example: If your App ID is “AcmeApp123”, scheme becomes otpless.acmeapp123
Additionally, ensure your activity is set to singleTop launch mode and that the exported attribute is true: 
android:launchMode="singleTop"
android:exported="true"

​
Silent Network Authentication (SNA) Setup

  • Make sure that Silent Network Authentication is enabled on the OTPLESS dashboard.
  • Once you have successfully integrated OTPLESS Android SDK in your application, you only have to add the following line in your app’s AndroidManifest file in the <application> tag:
Learn more about Silent Network Authentication.
android:networkSecurityConfig="@xml/otpless_network_security_config"

​
Step 3: Add SDK Initialization

Import OtplessSDK in your LoginActivity.ktfile: 
import com.otpless.v2.android.sdk.main.OtplessSDK;
initialize the SDK in your LoginActivity or LoginFragment depending upon your application architecture. In case of:
  • LoginActivity - Initialise the SDK in the onCreate() function
  • LoginFragment - Initialise the SDK in the onViewCreated() function.
OtplessSDK.initialize(appId = "YOUR_APPID", activity = activity)
OtplessSDK.setResponseCallback(this::onOtplessResponse)
Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

​
Step 4: Handle Callback

Now, let’s implement a callback method to handle the response from the OTPLESS SDK (SDK callback flow). 
private fun onOtplessResponse(response: OtplessResponse) {
    OtplessSDK.commit(response)
    when (response.responseType) {
        ResponseTypes.SDK_READY -> {
            // SDK has been initialized successfully, you may enable your continue button or proceed with user authentication.
        }
        ResponseTypes.FAILED -> {
            // Notify that the initialization failed
            if (response.statusCode == 5003) {
                // SDK initialization failed, please try to initialize the SDK again
            }
        }
        ResponseTypes.INITIATE -> {
            // notify that authentication has been initiated
             if (response.statusCode != 200) {
                handleInitiateError(response);
            } else {
                val authType = response.response?.optString("authType") // This is the authentication type
                if (authType == "OTP") {
                    // Take user to OTP verification screen
                } else if (authType == "SILENT_AUTH") {
                    // Handle Silent Authentication initiation by showing loading status for SNA flow.
                }
            }
        }
        ResponseTypes.OTP_AUTO_READ -> {
            val otp = response.response?.optString("otp")
            if (!otp.isNullOrBlank()) {
                // Autofill the OTP in your TextField/EditText
            }
        }
        ResponseTypes.VERIFY -> {
            // notify that verification has failed.
            if (response.response?.optString("authType") == "SILENT_AUTH") {
                if (response.statusCode == 9106) {
                    // Silent Authentication and all fallback authentication methods in SmartAuth have failed.
                    // The transaction cannot proceed further.
                    //  The transaction cannot proceed further. Handle the scenario to gracefully exit the authentication flow
                } else {
                    // Silent Authentication failed. If SmartAuth is enabled, the INITIATE response will include the next available authentication method configured in the dashboard.
                }
            } else {
                handleVerifyError(response)
            }
        }
        ResponseTypes.DELIVERY_STATUS -> {
            // This function is called when delivery is successful for your authType.
            val authType = response.response?.optString("authType") 
            // It is the authentication type (OTP, MAGICLINK, OTP_LINK) for which the delivery status is being sent
            val deliveryChannel = response.response?.optString("deliveryChannel")
            // It is the delivery channel (SMS, WHATSAPP, etc) on which the authType has been delivered
        }
        ResponseTypes.FALLBACK_TRIGGERED -> {
        // A fallback occurs when an OTP delivery attempt on one channel fails,  
        // and the system automatically retries via the subsequent channel selected on Otpless Dashboard.  
        // For example, if a merchant opts for SmartAuth with primary channal as WhatsApp and secondary channel as SMS,
        // in that case, if OTP delivery on WhatsApp fails, the system will automatically retry via SMS.
        // The response will contain the deliveryChannel to which the OTP has been sent.

        if (response.response != null) {
                val newDeliveryChannel = response.response.optString("deliveryChannel"); // This is the deliveryChannel to which the OTP has been sent
            }
        }
        ResponseTypes.ONETAP -> {
            // final response with ID token
            val idToken = response.response?.optJSONObject("data")?.optString("idToken")
            if (!idToken.isNullOrBlank()) {
                // Process idToken and proceed.
            }
            // final response with token
            val token = response.response?.optJSONObject("data")?.optString("token")
            if (!token.isNullOrBlank()) {
                // Process token and proceed.
            }
        }
    }
}

​
Handle Initiate Error Response:

    private fun handleInitiateError(response: OtplessResponse) {
        val errorCode = response.response?.get("errorCode") as? String
        val errorMessage = response.response?.get("errorMessage") as? String

        when (errorCode) {
            "7101" -> {
                // Handle request error: Invalid parameters values or missing parameters
                println("OTPless Error: $errorMessage")
            }

            "7102" -> {
                // Handle request error: Invalid phone number
                println("OTPless Error: $errorMessage")
            }

            "7103" -> {
                // Handle request error: Invalid phone number delivery channel
                println("OTPless Error: $errorMessage")
            }

            "7104" -> {
                // Handle request error: Invalid email
                println("OTPless Error: $errorMessage")
            }

            "7105" -> {
                // Handle request error: Invalid email channel
                println("OTPless Error: $errorMessage")
            }

            "7106" -> {
                // Handle request error: Invalid phone number or email
                println("OTPless Error: $errorMessage")
            }

            "7113" -> {
                // Handle request error: Invalid expiry
                println("OTPless Error: $errorMessage")
            }

            "7116" -> {
                // Handle request error: OTP Length is invalid (4 or 6 only allowed)
                println("OTPless Error: $errorMessage")
            }

            "7121" -> {
                // Handle request error: Invalid app hash
                println("OTPless Error: $errorMessage")
            }

            "4000" -> {
                // Handle invalid request values
                println("OTPless Error: $errorMessage")
            }

            "4003" -> {
                // Handle incorrect request channel
                println("OTPless Error: $errorMessage")
            }

            "401", "7025" -> {
                // Handle unauthorized request or country not enabled
                println("OTPless Error: $errorMessage")
            }

            "7020", "7022", "7023", "7024" -> {
                // Handle rate limiting errors (Too many requests)
                println("OTPless Error: $errorMessage")
            }

            "9100", "9104", "9103" -> {
                // Handle network connectivity errors
                println("OTPless Error: $errorMessage")
            }

            else -> {
                // Handle unknown error
                println("OTPless Error: $errorMessage")
            }
        }
    }

​
Handle Verify Response

fun handleVerifyError(response: OtplessResponse) {
        val errorCode = response.response?.get("errorCode") as? String
        val errorMessage = response.response?.get("errorMessage") as? String

        when (errorCode) {
            "7112" -> {
                // Handle request error: Empty OTP
                println("OTPless Error: $errorMessage")
            }

            "7115" -> {
                // Handle request error: OTP is already verified
                println("OTPless Error: $errorMessage")
            }

            "7118" -> {
                // Handle request error: Incorrect OTP
                println("OTPless Error: $errorMessage")
            }

            "7303" -> {
                // Handle request error: OTP expired
                println("OTPless Error: $errorMessage")
            }

            "4000" -> {
                // Handle invalid request
                println("OTPless Error: $errorMessage")
            }

            "9100", "9104", "9103" -> {
                // Handle network error: 
                println("OTPless Error: $errorMessage")
            }

            else -> {
                // Handle unknown error
                println("OTPless Error: $errorMessage")
            }
        }
    }
Override onNewIntent() 
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    lifecycleScope.launch {
        OtplessSDK.onNewIntent(intent)
    }
}

​
Error Codes

Checkout error codes here

​
Response Objects Structure

  • SDK_READY
  • FAILED
  • INITIATE
  • OTP_AUTO_READ
  • VERIFY
  • ONETAP
  • DELIVERY_STATUS
  • FALLBACK_TRIGGERED
{
   "responseType": "SDK_READY",
   "statusCode": 200,
   "response": {
       "success": true
    },
}

​
Step 5: Initiate Authentication

Well done! You have completed the foundational setup of the SDK. Now, let’s move to the next step and understand how to initiate and verify different authentication modes. Choose the authentication mode you want to integrate from the options below:
  • Phone Auth
  • Email Auth
  • OAUTH
Phone Authentication 📱
Phone authentication allows users to verify their identity using their phone number. Merchants can choose from various authentication methods:
  • Silent Authentication (SNA) – Automatically verifies the user without requiring OTP or MAGICLINK.
  • OTP on Desired Channel – Sends a one-time password (OTP) via SMS, WhatsApp, or another preferred channel.
  • Magic Link – Sends a link that users can click to authenticate.
  • SNA + OTP – Uses silent authentication first and falls back to OTP if needed.
  • OTP + Magic Link – Sends both an OTP and a magic link, allowing users to authenticate via either method.
final OtplessRequest otplessRequest = new OtplessRequest();
otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");
OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);

​
Verify OTP

To verify the OTP entered by the user, use the verify method with the necessary parameters. Verifying OTP is required only in case of OTP authentication. No need to verify OTP in case of MAGICLINK.
final OtplessRequest otplessRequest = new OtplessRequest();
otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE");
otplessRequest.setOtp("XXXXXX");
OtplessSDK.INSTANCE.startAsync(otplessRequest, this::onOtplessResponse);

Validate ID Token

Learn how to securely `validate ID token` returned by OTPLESS android SDK to ensure the authenticity of sign-in events from your backend server.

Validate Token (Opaque)

Learn how to securely `validate token` returned by OTPLESS android SDK to ensure the authenticity of sign-in events from your backend server.
⌘I