Headless

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.

Step 1: Install OTPLESS SDK Dependency

Install the OTPLESS SDK dependency by running the following command in your terminal at the root of your React Native project:

npm i otpless-headless-rn

Step 2: Platform-specific Integrations

Add intent filter inside your android/app/src/main/AndroidManifest.xml file into your Main activity code block:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
      android:host="otpless"
      android:scheme= "otpless.YOUR_APP_ID_IN_LOWERCASE"/>
</intent-filter>

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Add Network Security Config inside your android/app/src/main/AndroidManifest.xml file into your <application> code block (Only required if you are using the SNA feature):

android:networkSecurityConfig="@xml/otpless_network_security_config"

Change your activity launchMode to singleTop and exported true for your Main Activity:

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

Add intent filter inside your android/app/src/main/AndroidManifest.xml file into your Main activity code block:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
      android:host="otpless"
      android:scheme= "otpless.YOUR_APP_ID_IN_LOWERCASE"/>
</intent-filter>

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Add Network Security Config inside your android/app/src/main/AndroidManifest.xml file into your <application> code block (Only required if you are using the SNA feature):

android:networkSecurityConfig="@xml/otpless_network_security_config"

Change your activity launchMode to singleTop and exported true for your Main Activity:

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

Go to your project’s root folder in the terminal and run.

pod install

Add the following block to your info.plist file:

info.plist
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>otpless.YOUR_APP_ID_IN_LOWERCASE</string>
        </array>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>otpless</string>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>whatsapp</string>
    <string>otpless</string>
    <string>gootpless</string>
    <string>com.otpless.ios.app.otpless</string>
    <string>googlegmail</string>
</array>

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Add the following block to your info.plist file (Only required if you are using the SNA feature):

info.plist
<dict>
	<key>NSAllowsArbitraryLoads</key>
	<true/>
	<key>NSExceptionDomains</key>
	<dict>
		<key>80.in.safr.sekuramobile.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
			<true/>
			<key>NSTemporaryExceptionMinimumTLSVersion</key>
			<string>TLSv1.1</string>
		</dict>
		<key>partnerapi.jio.com</key>
		<dict>
			<key>NSIncludesSubdomains</key>
			<true/>
			<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
			<true/>
			<key>NSTemporaryExceptionMinimumTLSVersion</key>
			<string>TLSv1.1</string>
		</dict>
	</dict>
</dict>

Go to build settings. Search for defines module, this option will appear in packaging change it to yes.
Create connector.swift file and it will ask to create bridging header, Click yes. Copy-paste the following code into your connector.swift file.

connector.swift
import OtplessSDK
import Foundation
class Connector: NSObject {
  @objc public static func loadUrl(_ url: NSURL) {
    Task(priority: .userInitiated) {
      await Otpless.shared.handleDeeplink(url as URL)
    }
  }

  @objc public static func isOtplessDeeplink(_ url: NSURL) -> Bool {
    return Otpless.shared.isOtplessDeeplink(url: url as URL)
  }
}

Import the OTPLESS SDK in your respective AppDelegate.mm file to handle redirection.

#import "{{your_project_name}}-Swift.h"

- (BOOL) application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
	if([Connector isOtplessDeeplink:url]){
	[Connector loadUrl:url];
	return true;
}
	[super application:app openURL:url options:options];
	return true;
}

Replace your_project_name with your actual project name

Import the OtplessHeadlessModule on your page..

login_page.tsx
import { OtplessHeadlessModule } from 'otpless-headless-rn';

Create an instance of OtplessHeadlessModule.

login_page.tsx
const headlessModule = new OtplessHeadlessModule();

Use useEffect hook to initialize the OtplessHeadlessModule and set callback.

login_page.tsx
useEffect(() => {
      headlessModule.initialize("YOUR_APPID")
      headlessModule.setResponseCallback(onHeadlessResult);
      return () => {
          headlessModule.clearListener();
          headlessModule.cleanup();
      };
  }, []);

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Add a method to receive callbacks from OtplessHeadlessModule.

login_page.tsx
const onHeadlessResult = (result: any) => {
  headlessModule.commitResponse(result);
  const responseType = result.responseType;

  switch (responseType) {
    case "SDK_READY": {
      // Notify that SDK is ready
      console.log("SDK is ready");
      break;
    }
    case "FAILED": {
        console.log("SDK initialization failed");
        // Handle SDK initialization failure
      break;
    }
    case "INITIATE": {
      // Notify that headless authentication has been initiated
      if (result.statusCode == 200) {
        console.log("Headless authentication initiated");
        const authType = result.response.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.
        }
      } else {
        // Handle initiation error. 
        // To handle initiation error response, please refer to the error handling section.
        if (Platform.OS === 'ios') {
            handleInitiateErrorIOS(result.response);
        } else if (Platform.OS === 'android') {
            handleInitiateErrorAndroid(result.response);
        }
      }
      break;
    }
    case "OTP_AUTO_READ": {
        // OTP_AUTO_READ is triggered only in Android devices for WhatsApp and SMS.
      if (Platform.OS === "android") {
        const otp = result.response.otp;
        console.log(`OTP Received: ${otp}`);
      }
      break;
    }
    case "VERIFY": {
        // notify that verification has failed.
        if (result.response.authType == "SILENT_AUTH") {
            if (result.statusCode == 9106) {
                // Silent Authentication and all fallback authentication methods in SmartAuth have failed.
                //  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 {
            // To handle verification failed response, please refer to the error handling section.
            if (Platform.OS === 'ios') {
                handleVerifyErrorIOS(result.response);
            } else if (Platform.OS === 'android') {
                handleVerifyErrorAndroid(result.response);
            }
        }

      break;
    }
    case "DELIVERY_STATUS": {
        // This function is called when delivery is successful for your authType.
        const authType = result.response.authType;
        // It is the authentication type (OTP, MAGICLINK, OTP_LINK) for which the delivery status is being sent
        const deliveryChannel = result.response.deliveryChannel;
        // It is the delivery channel (SMS, WHATSAPP, etc) on which the authType has been delivered
    }

    case "ONETAP": {
      const token = result.response.token;
      if (token != null) {
        console.log(`OneTap Data: ${token}`);
      // Process token and proceed. 
      }
      break;
    }
    case "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.deliveryChannel != null) {
          const newDeliveryChannel = response.response.deliveryChannel 
          // This is the deliveryChannel to which the OTP has been sent
      }
      break;
    }
    default: {
      console.warn(`Unknown response type: ${responseType}`);
      break;
    }
  }

};

Step 4: Initiate Authentication

Initiate the authentication process based on the user’s selected method.

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.

const startPhoneAuth = (phoneNumber: string, countryCode: string) => {
  const request = {
      phone: phoneNumber,
      countryCode
  };
  headlessModule.start(request);
};

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.

const verifyPhoneOtp = (phoneNumber: string, countryCode: string, otp: string) => {
  const request = {
      phone: phoneNumber,
      countryCode,
      otp
  };
  headlessModule.start(request);
};

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.

const startPhoneAuth = (phoneNumber: string, countryCode: string) => {
  const request = {
      phone: phoneNumber,
      countryCode
  };
  headlessModule.start(request);
};

Verify OTP

const verifyPhoneOtp = (phoneNumber: string, countryCode: string, otp: string) => {
  const request = {
      phone: phoneNumber,
      countryCode,
      otp
  };
  headlessModule.start(request);
};

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.

const startEmailAuth = (email: string) => {
  const request = {
        email
    };
  headlessModule.start(request);
};

Verify OTP

const verifyEmailOtp = (email: string, otp: string) => {
  const request = {
        email,
        otp
    };
  headlessModule.start(request);
};

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.

This is the list of channels you can use for OAuth login:

WHATSAPP
APPLE
GMAIL
TWITTER
DISCORD
SLACK
FACEBOOK
LINKEDIN
MICROSOFT
LINE
LINEAR
NOTION
TWITCH
GITHUB
BITBUCKET
ATLASSIAN
GITLAB

const startOAuth = () => {
  const request = { channelType: "WHATSAPP" }; // Replace WHATSAPP with the desired channel
  headlessModule.start(request);
};

Make sure the channel that you have selected is enabled on the dashboard.

Error Handling

The error codes for android and iOS have to be handled separately.

Checkout android error codes
Checkout iOS error codes
To handle all the verification/initiation error codes for android and iOS, refer to the following code:

const handleInitiateErrorAndroid = (response: any) => {
    const errorCode = response?.errorCode as string;
    const errorMessage = response?.errorMessage as string;

    if (!errorCode) {
        console.log("OTPless Error: Unknown error -", errorMessage);
        return;
    }

    switch (errorCode) {
        case "7101":
            console.log("OTPless Error: Invalid parameters values or missing parameters -", errorMessage);
            break;
        case "7102":
            console.log("OTPless Error: Invalid phone number -", errorMessage);
            break;
        case "7103":
            console.log("OTPless Error: Invalid phone number delivery channel -", errorMessage);
            break;
        case "7104":
            console.log("OTPless Error: Invalid email -", errorMessage);
            break;
        case "7105":
            console.log("OTPless Error: Invalid email channel -", errorMessage);
            break;
        case "7106":
            console.log("OTPless Error: Invalid phone number or email -", errorMessage);
            break;
        case "7113":
            console.log("OTPless Error: Invalid expiry -", errorMessage);
            break;
        case "7116":
            console.log("OTPless Error: OTP Length is invalid (4 or 6 only allowed) -", errorMessage);
            break;
        case "7121":
            console.log("OTPless Error: Invalid app hash -", errorMessage);
            break;
        case "4000":
            console.log("OTPless Error: Invalid request values -", errorMessage);
            break;
        case "4001":
            console.log("OTPless Error: Unsupported 2FA request -", errorMessage);
            break;
        case "4003":
            console.log("OTPless Error: Incorrect request channel -", errorMessage);
            break;
        case "401":
        case "7025":
            console.log("OTPless Error: Unauthorized request or country not enabled -", errorMessage);
            break;
        case "7020":
        case "7022":
        case "7023":
        case "7024":
            console.log("OTPless Error: Too many requests (rate limiting) -", errorMessage);
            break;
        case "9002":
        case "9003":
        case "9004":
        case "9005":
        case "9006":
        case "9007":
        case "9008":
        case "9009":
            console.log("OTPless Error: Passkey authentication error -", errorMessage);
            break;
        case "500":
            console.log("OTPless Error: Unknown passkey error -", errorMessage);
            break;
        case "9100":
        case "9104":
        case "9103":
            console.log("OTPless Error: Network connectivity error -", errorMessage);
            break;
        default:
            console.log("OTPless Error: Unknown error -", errorMessage);
    }
};

const handleInitiateErrorAndroid = (response: any) => {
    const errorCode = response?.errorCode as string;
    const errorMessage = response?.errorMessage as string;

    if (!errorCode) {
        console.log("OTPless Error: Unknown error -", errorMessage);
        return;
    }

    switch (errorCode) {
        case "7101":
            console.log("OTPless Error: Invalid parameters values or missing parameters -", errorMessage);
            break;
        case "7102":
            console.log("OTPless Error: Invalid phone number -", errorMessage);
            break;
        case "7103":
            console.log("OTPless Error: Invalid phone number delivery channel -", errorMessage);
            break;
        case "7104":
            console.log("OTPless Error: Invalid email -", errorMessage);
            break;
        case "7105":
            console.log("OTPless Error: Invalid email channel -", errorMessage);
            break;
        case "7106":
            console.log("OTPless Error: Invalid phone number or email -", errorMessage);
            break;
        case "7113":
            console.log("OTPless Error: Invalid expiry -", errorMessage);
            break;
        case "7116":
            console.log("OTPless Error: OTP Length is invalid (4 or 6 only allowed) -", errorMessage);
            break;
        case "7121":
            console.log("OTPless Error: Invalid app hash -", errorMessage);
            break;
        case "4000":
            console.log("OTPless Error: Invalid request values -", errorMessage);
            break;
        case "4001":
            console.log("OTPless Error: Unsupported 2FA request -", errorMessage);
            break;
        case "4003":
            console.log("OTPless Error: Incorrect request channel -", errorMessage);
            break;
        case "401":
        case "7025":
            console.log("OTPless Error: Unauthorized request or country not enabled -", errorMessage);
            break;
        case "7020":
        case "7022":
        case "7023":
        case "7024":
            console.log("OTPless Error: Too many requests (rate limiting) -", errorMessage);
            break;
        case "9002":
        case "9003":
        case "9004":
        case "9005":
        case "9006":
        case "9007":
        case "9008":
        case "9009":
            console.log("OTPless Error: Passkey authentication error -", errorMessage);
            break;
        case "500":
            console.log("OTPless Error: Unknown passkey error -", errorMessage);
            break;
        case "9100":
        case "9104":
        case "9103":
            console.log("OTPless Error: Network connectivity error -", errorMessage);
            break;
        default:
            console.log("OTPless Error: Unknown error -", errorMessage);
    }
};

function handleInitiateErrorIOS(response: any) {
    const errorCode = response?.errorCode as string;
    const errorMessage = response?.errorMessage as string;

    if (!errorCode) {
      console.log("OTPless Error: Unknown error -", errorMessage);
      return;
    }

    switch (errorCode) {
        case "7101":
            console.log(`OTPless Error: Invalid parameters values or missing parameters - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7102":
            console.log(`OTPless Error: Invalid phone number - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7103":
            console.log(`OTPless Error: Invalid phone number delivery channel - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7104":
            console.log(`OTPless Error: Invalid email - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7105":
            console.log(`OTPless Error: Invalid email channel - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7106":
            console.log(`OTPless Error: Invalid phone number or email - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7113":
            console.log(`OTPless Error: Invalid expiry - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7116":
            console.log(`OTPless Error: OTP Length is invalid (4 or 6 only allowed) - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7121":
            console.log(`OTPless Error: Invalid app hash - ${errorMessage ?? "Unknown error"}`);
            break;
        case "4000":
            console.log(`OTPless Error: Invalid request values - ${errorMessage ?? "Unknown error"}`);
            break;
        case "4001":
            console.log(`OTPless Error: Unsupported 2FA request - ${errorMessage ?? "Unknown error"}`);
            break;
        case "4003":
            console.log(`OTPless Error: Incorrect request channel - ${errorMessage ?? "Unknown error"}`);
            break;
        case "401":
        case "7025":
            console.log(`OTPless Error: Unauthorized request or country not enabled - ${errorMessage ?? "Unknown error"}`);
            break;
        case "7020":
        case "7022":
        case "7023":
        case "7024":
            console.log(`OTPless Error: Rate limiting error (Too many requests) - ${errorMessage ?? "Unknown error"}`);
            break;

        // Feature not supported on older iOS versions
        case "5900":
            console.log(`OTPless Error: The feature is not supported because it requires a newer iOS version - ${errorMessage ?? "The requested feature is only available on newer iOS versions."}`);
            break;

        // Internet-related errors
        case "9100":
            console.log(`OTPless Error: Request Timeout - ${errorMessage ?? "The request took too long to complete and was aborted."}`);
            break;
        case "9101":
            console.log(`OTPless Error: Network Connection Was Lost - ${errorMessage ?? "The connection was interrupted before the request could complete."}`);
            break;
        case "9102":
            console.log(`OTPless Error: DNS Lookup Failed - ${errorMessage ?? "The domain name could not be resolved, possibly due to network issues."}`);
            break;
        case "9103":
            console.log(`OTPless Error: Cannot Connect to Server - ${errorMessage ?? "The server is unreachable, possibly due to downtime or incorrect configurations."}`);
            break;
        case "9104":
            console.log(`OTPless Error: No Internet Connection - ${errorMessage ?? "The device is not connected to the internet."}`);
            break;
        case "9105":
            console.log(`OTPless Error: Secure Connection Failed - ${errorMessage ?? "A secure connection could not be established due to SSL/TLS issues."}`);
            break;
        case "9110":
            console.log(`OTPless Error: Otpless Authentication Request Cancelled - ${errorMessage ?? "The authentication request was manually canceled by the user or the system."}`);
            break;

        default:
            console.log(`OTPless Error: ${errorMessage ?? "Unknown error"}`);
    }
}

Plugins

Web SDKs

Native/Mobile SDKs

References

Step 1: Install OTPLESS SDK Dependency

Step 2: Platform-specific Integrations

Step 4: Initiate Authentication

Verify OTP

Verify OTP

Verify OTP

Error Handling

Plugins

Web SDKs

Native/Mobile SDKs

References

​Step 1: Install OTPLESS SDK Dependency

​Step 2: Platform-specific Integrations

​Step 3: Configure Sign up/Sign in

​Step 4: Initiate Authentication

​Verify OTP

​Verify OTP

​Verify OTP

​Error Handling

Step 1: Install OTPLESS SDK Dependency

Step 2: Platform-specific Integrations

Step 3: Configure Sign up/Sign in

Step 4: Initiate Authentication

Verify OTP

Verify OTP

Verify OTP

Error Handling