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: Installation

Add the following to your pubspec.yaml:

dependencies:
  otpless_headless_flutter: ^<latest_version>

Then, run:

flutter pub get

Please find the latest version of the SDK here.

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_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_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 ios/Runner/info.plist file:

info.plist
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>otpless.YOUR_APP_ID_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 ios/Runner/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>

Import the OTPLESS SDK in your respective ios/Runner/AppDelegate.swift file to handle redirection.

import OtplessBM

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { 
    if Otpless.shared.isOtplessDeeplink(url: url.url) {
              Task(priority: .userInitiated) {
                  await Otpless.shared.handleDeeplink(url.url)
              }
      }
    return true 
}

Step 3: Initialize the SDK

Import the SDK in your main.dart file:

import 'package:otpless_headless_flutter/otpless_flutter.dart';

Then, create an instance of the SDK:

final _otplessHeadlessPlugin = Otpless();

In your LoginScreen’s initState, initialize the SDK and set the response callback:

LoginScreen
@override
void initState() {
  super.initState();
  _otplessHeadlessPlugin.initialize("YOUR_APP_ID");
  _otplessHeadlessPlugin.setResponseCallback(onOtplessResponse);
}

Create a callback function to handle the response:

LoginScreen
void onOtplessResponse(dynamic result) {
  _otplessHeadlessPlugin.commitResponse(result);

  final responseType = result['responseType'];

  switch (responseType) {
    case "SDK_READY":
      debugPrint("SDK is ready");
      break;

    case "FAILED":
      debugPrint("SDK initialization failed");
      // Handle SDK initialization failure
      break;

    case "INITIATE":
      if (result["statusCode"] == 200) {
        debugPrint("Headless authentication initiated");
        final 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.isAndroid) {
          handleInitiateErrorAndroid(result["response"]);
        } else if (Platform.isIOS) {  
          handleInitiateErrorIOS(result["response"]);
        }
      }
      break;

    case "OTP_AUTO_READ":
      // OTP_AUTO_READ is triggered only in ANDROID devices for WhatsApp and SMS.
        final otp = result["response"]["otp"];
        debugPrint("OTP Received: $otp");
      break;

    case "VERIFY":
      final authType = result["response"]["authType"];
      if (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.isAndroid) {
          handleVerifyErrorAndroid(result["response"]);
        } else if (Platform.isIOS) {  
          handleVerifyErrorIOS(result["response"]);
        }
      }
      break;

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

    case "ONETAP":
      final token = result["response"]["token"];
      if (token != null) {
        debugPrint("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.
        final newDeliveryChannel = result["response"]["deliveryChannel"];
        if (newDeliveryChannel != null) {
            // This is the deliveryChannel to which the OTP has been sent
        }
      break;

    default:
      debugPrint("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.

void startWithPhone(String phoneNumber) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

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.

void verifyPhoneOtp(String phoneNumber, String otp) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
        "otp": "otp",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

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.

void startWithPhone(String phoneNumber) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

Verify OTP

void verifyPhoneOtp(String phoneNumber, String otp) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
        "otp": "otp",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

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.

void startWithEmail(String email) {
    final Map<String, dynamic> args = {
        "email": email,
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

Verify OTP

void verifyEmailOtp(String email, String otp) {
    final Map<String, dynamic> args = {
        "email": email,
        "otp": otp,
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

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

void startWithOAuth(String channelType) {
    final Map<String, dynamic> args = {
        "channelType": "WHATSAPP", // Replace WHATSAPP with your desired channel
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

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:

void handleInitiateErrorAndroid(dynamic response) {
  final String? errorCode = response?['errorCode'];
  final String? errorMessage = response?['errorMessage'];

  if (errorCode == null) {
    debugPrint("OTPless Error: Unknown error - $errorMessage");
    return;
  }

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

void handleInitiateErrorAndroid(dynamic response) {
  final String? errorCode = response?['errorCode'];
  final String? errorMessage = response?['errorMessage'];

  if (errorCode == null) {
    debugPrint("OTPless Error: Unknown error - $errorMessage");
    return;
  }

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

void handleInitiateErrorIOS(dynamic response) {
  final String? errorCode = response?['errorCode'];
  final String? errorMessage = response?['errorMessage'];

  if (errorCode == null) {
    debugPrint("OTPless Error: Unknown error - ${errorMessage ?? 'Unknown error'}");
    return;
  }

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

    // iOS feature limitation
    case "5900":
      debugPrint("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":
    case "9101":
    case "9102":
    case "9103":
    case "9104":
    case "9105":
      debugPrint("OTPless Error: Network issue detected - ${errorMessage ?? 'A network error occurred. Please check your internet connection or try again later.'}");
      break;
    case "9110":
      debugPrint("OTPless Error: Otpless Authentication Request Cancelled - ${errorMessage ?? 'The authentication request was manually canceled by the user or the system.'}");
      break;

    default:
      debugPrint("OTPless Error: ${errorMessage ?? 'Unknown error'}");
  }
}

Validate Token

Learn how to securely `validate token` returned by OTPLESS flutter SDK to ensure the authenticity of sign-in events from your backend server.

Web SDKs

Native/Mobile SDKs

References

Step 1: Installation

Step 2: Platform-specific Integrations

Step 3: Initialize the SDK

Step 4: Initiate Authentication

Verify OTP

Verify OTP

Verify OTP

Error Handling

Validate Token

Web SDKs

Native/Mobile SDKs

References

​Step 1: Installation

​Step 2: Platform-specific Integrations

​Step 3: Initialize the SDK

​Step 4: Initiate Authentication

​Verify OTP

​Verify OTP

​Verify OTP

​Error Handling

Validate Token

Step 1: Installation

Step 2: Platform-specific Integrations

Step 3: Initialize the SDK

Step 4: Initiate Authentication

Verify OTP

Verify OTP

Verify OTP

Error Handling