Step 1: Install OTPLESS SDK Dependency

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

flutter pub add otpless_flutter:2.2.1
flutter pub get

Step 2: Platform-specific Integrations

  1. 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.

  1. 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"
  1. Change your activity launchMode to singleTop and exported true for your Main Activity:
android:launchMode="singleTop"
android:exported="true"
  1. Add the following override method in android/app/src/main/kotlin/MainActivity.kt to handle callback:
  • Import the following classes:
import com.otpless.otplessflutter.OtplessFlutterPlugin;
import android.content.Intent;

  • Add this code to your onBackPressed() method in your main activity:
override fun onBackPressed() {
    val plugin = flutterEngine?.plugins?.get(OtplessFlutterPlugin::class.java)
    if (plugin is OtplessFlutterPlugin) {
      if (plugin.onBackPressed()) return
  }
  // handle other cases
  super.onBackPressed()
}

Step 3: Initialize OTPless

  1. Import the OTPLESS package on your login page.
login_page.dart
import 'package:otpless_flutter/otpless_flutter.dart';
  1. Create an instance of otpless plugin in your dart file.
login_page.dart
final _otplessFlutterPlugin = Otpless();
  1. Override the initState function and add the following code:
login_page.dart
_otplessFlutterPlugin.initHeadless("YOUR_APP_ID");
_otplessFlutterPlugin.setHeadlessCallback(onHeadlessResult);

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

  1. Add a method to receive callbacks from OTPless
login_page.dart
void onHeadlessResult(dynamic result) {
    if (result['statusCode'] == 200) {
      switch (result['responseType'] as String) {
        case 'INITIATE':
          {
            // notify that headless authentication has been initiated
          }
          break;
        case 'VERIFY':
          {
            // notify that verification is completed
            // and this is notified just before "ONETAP" final response
          }
          break;
        case 'OTP_AUTO_READ':
          {
            if (Platform.isAndroid) {
              var otp = result['response']['otp'] as String;
            }
          }
          break;
        case 'ONETAP':
          {
             final token = result["response"]["token"];
          }
          break;
      }
    } else {
      //todo
    }
}
ResponseTypeDescription
INITIATEWhen authentication is initiated.
VERIFYWhen OTP is verified for an authentication and in case of link based authentication when user redirected back to the application after clicking the link.
ONETAPThis is the final response of an authentication session. It includes the token that should be sent to your backend for server-to-server validation.
OTP_AUTO_READWhen the OTP is automatically retrieved from SMS or WhatsApp. It includes OTP value in this responseType

Error Codes

StatusCodeErrorMessageShort Description
401Unauthorized request! Please check your appIdSuggests missing or invalid app ID for authorization.
500API_ERRORIndicates a server-side error, possibly due to parameter issues.
4000The request values are incorrect, see details.Points to incorrect request values; refer to details for corrections.
4001OTPless headless SDK doesn’t support 2FA as of nowIndicates the lack of 2FA support in the SDK.
4002The request parameters are incorrect, see details.Suggests parameter errors; check details for specifics.
4003The request channel is incorrect, see details.Notes an incorrect request channel; see details for correct usage.
5002No internet connection is present.Indicates no internet connection, troubleshoot network and device.

Step 4: Initiate Authentication

Initiate the authentication process based on the user’s selected method by using the initiate method of the SDK.

(Optional): Verify OTP

To verify the OTP entered by the user, use the verify method with the necessary parameters.

Object Attributes

AttributeMandatoryDescription
channelYesThe authentication method selected by the user.
phoneConditionalUser’s phone number (required if channel is PHONE).
countryCodeConditionalCountry code of the phone number (required if channel is PHONE).
emailConditionalUser’s email (required if channel is EMAIL).
channelTypeConditionalType of social login initiated (required if channel is OAUTH).

🏁 Checkpoint

To ensure a smooth integration process:

  1. Deploy your app/website with the included OTPLESS SDK.
  2. Conduct tests to verify the sign-in flow functions correctly.
  3. Ensure that after a successful sign-in, the user is redirected back to your app/website and their information is correctly logged in the console.

User Information Response Structure

The structure of the user information returned upon successful sign-in is as follows:

{
  "status": "SUCCESS",
  "token": "unique_token_here",
  "userId": "unique_user_id_here",
  "timestamp": "ISO_timestamp_here",
  "identities": [
    {
       "identityType": "EMAIL",
      "identityValue": "user@example.com",
      "channel": "OAUTH",
      "methods": [
        "GOOGLE"
      ],
      "name": "User Name",
      "verified": true,
      "verifiedAt": "ISO_timestamp_here",
      "isCompanyEmail": "true"
    }
  ],
  "idToken": "jwt_token",
  "network": {
    "ip": "127.0.0.1",
    "timezone": "Asia/Kolkata",
    "ipLocation": {}
  },
  "deviceInfo": {},
  "sessionInfo": {},
  "firebaseInfo": {},
}

You can check out a complete sample response here.

Next Steps