Skip to main content
This page covers the SNA-only integration of the OTPless Headless SDK on Android. The SDK accepts the requestId generated by the Create API, performs the silent network handshake, and reports progress through callbacks. Your backend confirms the final result via the Status Check API.

​
Requirements

RequirementVersion
compileSdk35
Minimum SDK21
Kotlin1.9.0+
Gradle8.3.1+

​
Step 1: Add SDK dependency

Add the OTPLESS SDK to your app’s build.gradle: 
implementation ("io.github.otpless-tech:otpless-headless-lite:latest_version")
Check the latest version of the SDK here. Make sure to synchronize your Gradle project to fetch the dependency.

​
Step 2: Smart Authentication (SNA) setup

Make sure Silent Network Authentication is enabled on the OTPLESS dashboard. For an SNA-only configuration, SNA must be the only channel enabled.
Once the SDK is integrated, add the following line in your app’s AndroidManifest.xml inside the <application> tag:
AndroidManifest.xml
android:networkSecurityConfig="@xml/otpless_network_security_config"

​
Step 3: Initialize the SDK

Import OtplessSDK in your LoginActivity.kt: 
import com.otpless.v2.android.sdk.main.OtplessSDK
Initialize the SDK depending on your app architecture:
  • LoginActivity — initialize in onCreate()
  • LoginFragment — initialize in onViewCreated()
lifecycleScope.launch(Dispatchers.IO) {
    OtplessSDK.initialize(
        APP_ID,
        this@LoginActivity,
        callback = this@LoginActivity::onOtplessResponse
    )
}
Replace APP_ID with your actual App ID from the OTPLESS dashboard.

​
Step 4: Start SNA with the requestId

Pass the requestId returned by the Create API to start(): 
val otplessRequest = OtplessRequest()
otplessRequest.requestId = "REQUEST_ID_FROM_API"

lifecycleScope.launch {
    OtplessSDK.start(request = otplessRequest, callback = ::onOtplessResponse)
}
Start polling the Status Check API from your backend immediately after calling start(). The SDK callback and the server status run in parallel.

​
Step 5: Handle callbacks

private fun onOtplessResponse(response: OtplessResponse) {
    OtplessSDK.commit(response)
    when (response.responseType) {
        ResponseTypes.SDK_READY -> {
            // SDK initialized successfully — enable your continue button
            // or proceed with user authentication.
        }
        ResponseTypes.FAILED -> {
            // SDK initialization failed
            if (response.statusCode == 5003) {
                // Please try to initialize the SDK again.
            }
        }
        ResponseTypes.INITIATE -> {
            // Authentication has been initiated
            if (response.statusCode != 200) {
                handleInitiateError(response)
            } else {
                val authType = response.response
                    ?.optString("authType")
                if (authType == "SILENT_AUTH") {
                    // SNA is being attempted — show a loading state.
                }
            }
        }
        ResponseTypes.ONETAP -> {
            // Final success response
        }
        ResponseTypes.AUTH_TERMINATED -> {
            // SNA-only configuration: auth could not complete.
            // Emitted when pre-checks fail, or when SNA was attempted
            // and then failed/expired. Treat as a terminal failure and
            // rely on the Status Check API for the exact error.
        }
    }
}

​
Callback reference

The SDK works in two steps — initialization and start() — and each step has its own set of callbacks.

​
Step 1: Initialization callbacks

Emitted when you initialize the SDK (Step 3).
CallbackMeaning
SDK_READYSDK initialization completed.
FAILEDSDK failed to initialize (e.g. statusCode 5003).

​
Step 2: Start callbacks

Emitted after you invoke start() (Step 4).
CallbackStateMeaning
INITIATENon-terminalSNA is being attempted after pre-checks pass. authType is SILENT_AUTH.
ONETAPSuccess — terminalSNA completed successfully (Silent Mobile Verification). Returns token / idToken.
AUTH_TERMINATEDFailed — terminalEmitted in two cases: (1) pre-checks failed → terminated directly; (2) SNA was initiated and then failed/expired.
In the SNA-only configuration AUTH_TERMINATED is a terminal failure with no fallback. Always treat the Status Check API result as authoritative. See Handling the AUTH_TERMINATED callback.
For the errorCode / statusCode values surfaced in SDK callbacks, see SDK Error Codes.

​
Next step

Status Check API

Confirm the authoritative auth status from your server.