The three building blocks
The integration is built from three pieces that work together regardless of platform (Android or iOS):| Step | Component | Where it runs | Purpose |
|---|---|---|---|
| 1. Create | Create API | Your server → OTPless Server | Registers the user’s identity (phone number) and returns a requestId that links the identity to a future auth flow. |
| 2. Initialize & Start | Android SDK / iOS SDK | Client app | Initializes the SDK, then starts SNA with the requestId. The SDK drives the silent network handshake and emits lifecycle callbacks. |
| 3. Status Check | Status Check API | Your server → OTPless Server | Your backend polls the consolidated auth status for the requestId and decides the final outcome. |
How the SDK and APIs stitch together
TherequestId is the thread that ties every step together:
- Your server calls Create with the user’s phone number and receives a
requestId. - Your server hands the
requestIdback to the client app. - The client app passes the
requestIdto the SDK viastart(). - The SDK performs the silent network handshake with the Telco Server and reports progress through callbacks.
- Independently, your server polls Status Check with the same
requestIdto 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 callingstart(requestId), while the SDK runs the SNA handshake in parallel.
How to perform the status check
There are two ways to drive the Status Check API poll:Option 1: Poll right after start()
Option 1: Poll right after start()
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.Option 2: Poll once after the SDK terminal callback (recommended)
Option 2: Poll once after the SDK terminal callback (recommended)
Wait for the SDK to emit a terminal callback (
ONETAP or AUTH_TERMINATED), and only then call the Status Check API once to fetch the final, authoritative status.This makes a single call instead of repeated polling, but it relies on the SDK callback being delivered to the client.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 thestart() method to begin authentication.
Step 1: Initialization callbacks
Emitted when you initialize the SDK.| Callback | State | Meaning |
|---|---|---|
SDK_READY | Non-terminal | SDK initialized successfully. You may enable the continue button or proceed with auth. |
FAILED | Terminal | SDK failed to initialize. Retry initialization. |
Step 2: Start callbacks
Emitted after you invokestart() to begin authentication.
| Callback | State | Meaning |
|---|---|---|
INITIATE | Non-terminal | Backend pre-checks passed and SNA is being attempted. Show a loading state. |
ONETAP | Success — terminal | SNA completed successfully. |
AUTH_TERMINATED | Failed — terminal | Auth could not complete. Emitted either because pre-checks failed, or because SNA was attempted and then failed/expired. |
What to read next
Create API
Generate a
requestId from the user’s phone number.Android SDK
Initialize and start SNA on Android.
iOS SDK
Initialize and start SNA on iOS.
Status Check API
Poll the authoritative auth status from your server.