Web SDK - OTPLESS

This page covers the integration of the OTPless Headless Web SDK. The SDK accepts the requestId generated by the Create API, performs the authentication, and reports progress through events. Your backend confirms the final result via the Status Check API.

npm
Script Tag

Step 1: Install the SDK

Install the OTPless Headless SDK with your favorite package manager:

npm install otpless-headless-js
# or
yarn add otpless-headless-js
# or
pnpm add otpless-headless-js

Check the latest version of the SDK on npm.

Make sure your authentication channel is enabled on the OTPLESS dashboard.

Step 2: Initialize the SDK

Initialize the SDK with your App ID and subscribe to its events. The useOTPless() hook is available for React; for any other framework, use the otpless object.

import { useEffect } from 'react';
import { useOTPless, EVENT_TYPES } from 'otpless-headless-js';

function Login() {
  const { init, initiate, on, ready, loading } = useOTPless();

  useEffect(() => {
    init('YOUR_APP_ID');
    const unsubscribe = on({
      [EVENT_TYPES.FAILED]: onFailed,
      [EVENT_TYPES.INITIATE]: onInitiate,
      [EVENT_TYPES.ONETAP]: onOneTap,
    });
    return () => unsubscribe();
  }, [init, on]);

  // ...
}

import { otpless, EVENT_TYPES } from 'otpless-headless-js';

await otpless.init('YOUR_APP_ID');

const unsubscribe = otpless.on({
  [EVENT_TYPES.FAILED]: onFailed,
  [EVENT_TYPES.INITIATE]: onInitiate,
  [EVENT_TYPES.ONETAP]: onOneTap,
});

Replace YOUR_APP_ID with your actual App ID from the OTPLESS dashboard. For the Next.js App Router, add 'use client'; at the top of the component file.

Initialization is not reported as an event. In React, gate on the ready flag returned by useOTPless(); elsewhere, await otpless.init() before calling initiate(). A failed initialization arrives on FAILED with statusCode 5003.

Step 3: Initiate authentication with the requestId

Call initiate() with your normal authentication payload — channel plus the user’s phone/countryCode or email — and append the requestId returned by the Create API.

import type { OTPlessResponse } from 'otpless-headless-js';

const startAuth = async () => {
  if (!ready) return;

  const res: OTPlessResponse = await initiate({
    channel: 'PHONE',
    phone: '9876543210',
    countryCode: '+91',
    requestId: 'REQUEST_ID_FROM_API',
  });

  if (!res.success) {
    console.error('initiate failed:', res.response?.errorMessage);
  }
};

const res = await otpless.initiate({
  channel: 'PHONE',
  phone: '9876543210',
  countryCode: '+91',
  requestId: 'REQUEST_ID_FROM_API',
});

if (!res.success) {
  console.error('initiate failed:', res.response?.errorMessage);
}

The requestId is appended to your usual payload — it does not replace any field. Keep sending channel and the identity exactly as you do for a standard headless integration.

Send the same identity you passed to the Create API. The server resolves the identity bound to the requestId and uses that one, so if the two disagree the requestId silently wins and the number you passed is ignored.

Start polling the Status Check API from your backend immediately after calling initiate(). The SDK events and the server status run in parallel.

Step 4: Handle events

const onFailed = (event) => {
  // Terminal failure — initialization failed, or authentication was
  // attempted and then failed / expired.
  if (event.statusCode === 5003) {
    // Initialization failed. Call init() again.
  }
  // Rely on the Status Check API for the authoritative error.
};

const onInitiate = (event) => {
  // Authentication has been initiated
  if (event.statusCode !== 200) {
    handleInitiateError(event);
  } else {
    // Authentication is in progress — show a loading state.
  }
};

const onOneTap = (event) => {
  // Final success response — returns token / idToken
  const { token, idToken } = event.response ?? {};
  // Verify the token on your backend.
};

Step 1: Add the SDK script

Add the OTPLESS SDK to your project by including the following script in the <head> section of your HTML document:

index.html

<script
  id="otpless-sdk"
  src="https://otpless.com/v4.3/headless.js"
  data-appid="YOUR_APP_ID"
></script>

Use the v4.3 path — /v4/headless.js will not work for this flow. It is not an older build of the same SDK: the v4 bundle ships a different headless implementation with no requestId support at all. The requestId field exists only on the v4.1+ builds, and v4.3 is the current one.Keep id="otpless-sdk" too — the SDK reads both its App ID and its version from that element.

Replace YOUR_APP_ID with your actual App ID from the OTPLESS dashboard.

Make sure your authentication channel is enabled on the OTPLESS dashboard.

Step 2: Initialize the SDK and register the callback

Create an OTPless instance with a callback. Every event is delivered to this callback with its responseType:

index.html

<script>
  const callback = (event) => {
    const EVENTS_MAP = {
      FAILED: onFailed,
      INITIATE: onInitiate,
      ONETAP: onOneTap,
    };

    if ("responseType" in event) EVENTS_MAP[event.responseType]?.(event);
  };

  // Initialize the OTPLESS SDK with the callback.
  const OTPlessSignin = new OTPless(callback);
</script>

Initialization is not reported as an event on this integration. Use the OTPlessSignin.isReady() method to check whether the SDK has finished initializing before calling initiate(); a failed initialization arrives on the FAILED callback with statusCode 5003.

Step 3: Call initiate() with the requestId

Call initiate() with your normal authentication payload — channel plus the user’s phone/countryCode or email — and append the requestId returned by the Create API.

const startAuth = async () => {
  const res = await OTPlessSignin.initiate({
    channel: "PHONE",
    phone: "9876543210",
    countryCode: "+91",
    requestId: "REQUEST_ID_FROM_API",
  });

  if (!res.success) {
    console.error("initiate failed:", res.response?.errorMessage);
  }
};

The requestId is appended to your usual payload — it does not replace any field. Keep sending channel and the identity exactly as you do for a standard headless integration.

Start polling the Status Check API from your backend immediately after calling initiate(). The SDK events and the server status run in parallel.

Step 4: Handle events in the callback

const onFailed = (event) => {
  // Terminal failure — initialization failed, or authentication was
  // attempted and then failed / expired.
  if (event.statusCode === 5003) {
    // Initialization failed. Re-create the OTPless instance.
  }
  // Rely on the Status Check API for the authoritative error.
};

const onInitiate = (event) => {
  // Authentication has been initiated
  if (event.statusCode !== 200) {
    handleInitiateError(event);
  } else {
    // Authentication is in progress — show a loading state.
  }
};

const onOneTap = (event) => {
  // Final success response — returns token / idToken
  const { token, idToken } = event.response ?? {};
  // Verify the token on your backend.
};

Response type

initiate() and every event deliver an OTPlessResponse:

type OTPlessResponse = {
  responseType: string;
  response?: {
    token?: string;
    idToken?: string;
    errorCode?: string;
    errorMessage?: string;
    [key: string]: any;
  };
  success: boolean;
  statusCode: number;
};

Event reference

These are the responseType values the Web SDK delivers to your callback.

Event	State	Meaning
`INITIATE`	Non-terminal	Authentication is in progress after pre-checks pass.
`ONETAP`	Success — terminal	Authentication completed successfully. Returns `token` / `idToken`.
`FAILED`	Failed — terminal	Terminal failure: the SDK could not initialize (`statusCode 5003`), or authentication was attempted and then failed / expired.

| OTP_AUTO_READ | Non-terminal | Mobile browsers only, OTP channels only — the OTP was read automatically. Optional to handle. |

Readiness is not an event on the web. Unlike the Android and iOS SDKs, the Web SDK emits no SDK_READY callback — check initialization with isReady() on the script tag, or the ready flag / await init() on npm. There is likewise no separate AUTH_TERMINATED event; terminal authentication failures arrive on FAILED.

This table covers the events relevant to the server-initiated flow. For the Web SDK’s full event and method surface, see the Headless Web SDK reference.

FAILED is a terminal failure. Always treat the Status Check API result as authoritative.

For the errorCode / statusCode values surfaced in SDK events, see SDK Error Codes.

Next step

Status Check API

Confirm the authoritative auth status from your server.

​Step 1: Install the SDK

​Step 2: Initialize the SDK

​Step 3: Initiate authentication with the requestId

​Step 4: Handle events

​Step 1: Add the SDK script

​Step 2: Initialize the SDK and register the callback

​Step 3: Call initiate() with the requestId

​Step 4: Handle events in the callback

​Response type

​Event reference

​Next step

Status Check API

Step 1: Install the SDK

Step 2: Initialize the SDK

Step 3: Initiate authentication with the requestId

Step 4: Handle events

Step 1: Add the SDK script

Step 2: Initialize the SDK and register the callback

Step 3: Call initiate() with the requestId

Step 4: Handle events in the callback

Response type

Event reference

Next step