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:

This step is only needed for Magic Link. Smart Auth integration do not require this manifest intent-filter.

<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:

This step is only needed for Magic Link. Smart Auth integration do not require this manifest intent-filter.

android:launchMode="singleTop"
android:exported="true"

Smart 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.

lifecycleScope.launch(Dispatchers.IO) {
    OtplessSDK.initialize(APP_ID, this@LoginActivity, callback = this@LoginActivity::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.
            }
        }
        ResponseTypes.AUTH_TERMINATED -> {
                // Optional handling
                // This callback is given in SNA only configuration[SNA is only channel]
                // No action is required if Smart auth is fully configured
        }
        ResponseTypes.AUTO_FLOW_ACTION -> {
            // Optional handling
            // This callback is given in background auth case
            // No action is required if background auth is not triggered
            if (response.statusCode == 200) {
                val actionType = response.response?.getString("actionType")
                // 21000 = identity selected
                // 21001 = dialog shown
            } else {
                val errorCode = response.response?.getString("errorCode")
                // 12001 = user aborted the auth
                // 12002 = network failure abort
            }
        }
    }
}

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()

onNewIntent overriding is only needed for Magic Link. Smart Auth integration do not require this step.

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    lifecycleScope.launch {
        OtplessSDK.onNewIntent(intent)
    }
}

Error Codes

Checkout error codes here

Response Objects Structure

{
   "responseType": "SDK_READY",
   "statusCode": 200,
   "response": {
       "success": true
    },
}

 {
    "responseType": "FAILED",
    "statusCode": 5003,
    "response": {
        "errorCode": "5003",
        "errorMessage": "Failed to initialize the SDK"
    }
}

{
    "responseType": "INITIATE",
    "statusCode": 200,
    "response": {
        "requestId": "abc123xyz",
        "channel": "MOBILE_LOGIN",
        "authType": "MOBILE_LOGIN",
        "deliveryChannel": "SMS",
    }
}

{
    "responseType": "OTP_AUTO_READ",
    "statusCode": 200,
    "response": {
        "otp": "482913"
    }
}

All VERIFY response types will always return a non-200 status code.

 {
    "responseType": "VERIFY",
    "statusCode": 400,
    "response": {
        "errorCode":"7118",
        "errorMessage":"Request error: Incorrect OTP!",
        "authType":"OTP"
    }
}

{
    "responseType": "ONETAP",
    "statusCode": 200,
    "response": {
        "token": "your_token_here",
        "status": "SUCCESS",
        "userId": "userId_for_identity",
        "timestamp": "2024-07-11T12:51:42Z",
        "identities": [],
        "idToken": "jwt_token",
        "network": {},
        "deviceInfo": {},
        "sessionInfo": { },
        "firebaseInfo": {}
    }
}

{
    "responseType": "DELIVERY_STATUS",
    "statusCode": 200,
    "response": {
        "deliveryChannel": "WHATSAPP",
        "communicationDelivered": true,
        "authType": "OTP"
    }
}

{
    "responseType": "FALLBACK_TRIGGERED",
    "statusCode": 200,
    "response": {
        "requestId": "req_98765abc",
        "channel": "MOBILE_LOGIN",
        "authType": "MOBILE_LOGIN",
        "deliveryChannel": "SMS"
    }
}

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.

val isSdkReady = OtplessSDK.isSdkReady();
if (isSdkReady) {
    val otplessRequest = OtplessRequest()
    otplessRequest.setPhoneNumber(number = "PHONE_NUMBER", countryCode = "COUNTRY_CODE")
    lifecycleScope.launch {
        OtplessSDK.start(request = otplessRequest, callback = ::onOtplessResponse)
    }
}else{
    console.log("SDK is not ready");
    // Follow Fallback mechanism to handle the authentication flow.
}

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.

  val otplessRequest = OtplessRequest()
  otplessRequest.setPhoneNumber("PHONE_NUMBER", "COUNTRY_CODE")
  otplessRequest.setOtp("XXXXXX")
  lifecycleScope.launch {
    OtplessSDK.start(otplessRequest, ::onOtplessResponse)
  }

Email Authentication 📧
Email authentication verifies users using their email address. Merchants can choose from:

OTP via Email – Sends a one-time password to the user’s email.
Magic Link – Sends a clickable authentication link to the email.
OTP + Magic Link – Provides both options for flexibility.

  val otplessRequest = OtplessRequest()
  otplessRequest.setEmail("EMAIL_INPUT")
  lifecycleScope.launch {
    OtplessSDK.start(otplessRequest, ::onOtplessResponse)
  }

Verify OTP

val otplessRequest = OtplessRequest()
otplessRequest.setEmail("EMAIL_INPUT")
otplessRequest.setOtp("XXXXXX")
lifecycleScope.launch {
OtplessSDK.start(otplessRequest, ::onOtplessResponse)
}

OAuth Authentication 🔑
OAuth allows users to authenticate using third-party services like Google, GitHub, or WhatsApp. Instead of entering credentials manually, users can log in using their existing accounts, streamlining the authentication process.

val request = OtplessRequest()
request.setChannelType(OtplessChannelType.SOCIAL_CHANNEL_NAME)
lifecycleScope.launch {
    OtplessSDK.start(request, ::onOtplessResponse)
}

Web SDKs

Native/Mobile SDKs

References

Headless

Overview

Integration Steps

Step 1: Add SDK Dependency

Step 2: Update AndroidManifest.xml

Smart Authentication (SNA) Setup

Step 3: Add SDK Initialization

Step 4: Handle Callback

Handle Initiate Error Response:

Handle Verify Response

Error Codes

Response Objects Structure

Step 5: Initiate Authentication

Verify OTP

Verify OTP

Web SDKs

Native/Mobile SDKs

References

​Overview

​Integration Steps

​Step 1: Add SDK Dependency

​Step 2: Update AndroidManifest.xml

​Smart Authentication (SNA) Setup

​Step 3: Add SDK Initialization

​Step 4: Handle Callback

​Handle Initiate Error Response:

​Handle Verify Response

​Error Codes

​Response Objects Structure

​Step 5: Initiate Authentication

​Verify OTP

​Verify OTP

Overview

Integration Steps

Step 1: Add SDK Dependency

Step 2: Update AndroidManifest.xml

Smart Authentication (SNA) Setup

Step 3: Add SDK Initialization

Step 4: Handle Callback

Handle Initiate Error Response:

Handle Verify Response

Error Codes

Response Objects Structure

Step 5: Initiate Authentication

Verify OTP

Verify OTP