Skip to main content
This guide covers the SDK-based authentication integration using the OTPless SDK. The flow is designed for backend-controlled, server-verified authentication: your server creates the auth request, the client app runs it through the SDK, and your server confirms the result.

​
The three building blocks

The integration is built from three pieces that work together regardless of platform (Android, iOS, or web):
The server is the source of truth. Your backend must rely on the Status Check API result — not the SDK callback alone — to confirm a successful login.

​
How the SDK and APIs stitch together

The requestId is the thread that ties every step together:
  1. Your server calls Create with the user’s identity and receives a requestId.
  2. Your server hands the requestId back to the client app.
  3. The client app passes the requestId to the SDK via start().
  4. The SDK performs the authentication with the OTPless Server and reports progress through callbacks.
  5. Independently, your server polls Status Check with the same requestId to determine the final, authoritative result.

​
Data flow

The flow is the same on every platform — only the SDK calls differ. The client app starts polling its own backend immediately after calling start(requestId), while the SDK runs the authentication in parallel.

​
How to perform the status check

There are two ways to drive the Status Check API poll:
Begin polling from your backend immediately after calling the SDK start() method, and keep polling until you receive a terminal state (SUCCESS or FAILED).Always enforce a timeout threshold — if no terminal state is reached within that window, stop polling and mark the transaction as failed (timeout). This prevents the poll from running indefinitely if the flow never resolves.
Regardless of the approach, the Status Check API result from your server — not the SDK callback alone — is the source of truth for confirming a successful login.

​
SDK callback states

The SDK works in two steps, and each step has its own set of callbacks. First, the SDK must be initialized. Once initialization succeeds, you invoke the start() method to begin authentication.

​
Step 1: Initialization callbacks

Emitted when you initialize the SDK.

​
Step 2: Start callbacks

Emitted after you invoke start() to begin authentication.
The callbacks above describe the Android and iOS SDKs. The Web SDK differs: authentication is started with initiate() rather than start(), readiness is read from isReady() instead of an SDK_READY callback, and terminal failures arrive on FAILED instead of AUTH_TERMINATED. See the Web SDK page.

Create API

Generate a requestId from the user’s phone number or email.

Android SDK

Initialize and start authentication on Android.

iOS SDK

Initialize and start authentication on iOS.

Web SDK

Initialize and initiate authentication on the web.

Status Check API

Poll the authoritative auth status from your server.