Headless

Step 1: Add SDK Dependency

Begin by adding the OTPLESS SDK to your project. Insert the following script tag in the <head> section of your HTML document.

index.html

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

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

Step 2: Initialize SDK and Handle Callback

With the SDK embedded, initialize it and define a callback function to handle authentication responses as shown below.

index.html

<script>
 const callback = (eventCallback) => {

    // console.log({eventCallback});
    
    const ONETAP = () => {
        const {
            response
        } = eventCallback;
        const token = response.token;
        // Implement your custom logic here.
        console.log({
            response,
            token: response.token
        });
    };

    const OTP_AUTO_READ = () => {
        const {
            response: {
                otp
            }
        } = eventCallback;
         // Auto-read OTP value
        //console.log(otp);
    }

    const FAILED = () => {
        const {
            response
        } = eventCallback;

        console.log({
            response
        })
    }

    const FALLBACK_TRIGGERED = () => {
        const {
            response
        } = eventCallback;

        console.log({
            response
        })
    }


    const EVENTS_MAP = {
        ONETAP,
        OTP_AUTO_READ,
        FAILED,
        FALLBACK_TRIGGERED
    }

    if ("responseType" in eventCallback) EVENTS_MAP[eventCallback.responseType]()
}
  // Initialize OTPLESS SDK with the defined callback.
  const OTPlessSignin = new OTPless(callback);
</script>

Step 3: Create Your UI

Design a user interface for authentication. An example HTML structure could look like this:

<div>
  <input id="mobile-input" placeholder="Enter mobile number" />
  <button onclick="phoneAuth()">Request OTP</button>
</div>

<div id="otp-section" style="display: none;">
  <input id="otp-input" placeholder="Enter OTP" />
  <button onclick="verifyOTP()">Verify OTP</button>
</div>

<button onclick="oauth('WHATSAPP')">Continue with WhatsApp</button>
<button onclick="oauth('GMAIL')">Continue with Gmail</button>
<!-- Add more buttons for different OAuth providers as needed -->

Step 4: Initiate Authentication

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

const phoneAuth = () => {
  OTPlessSignin.initiate({
    channel: "PHONE",
    phone: "839899038845",
    countryCode: "+62",
  });
};

const emailAuth = () => {
  OTPlessSignin.initiate({ channel: "EMAIL", email: "user@example.com" });
};

const oauth = (provider) => {
  OTPlessSignin.initiate({ channel: "OAUTH", channelType: provider });
};

Object Attributes

Request
Response
Error Codes

Attribute	Mandatory	Description
`channel`	Yes	The authentication method selected by the user.
`phone`	Conditional	User’s phone number (required if channel is PHONE).
`countryCode`	Conditional	Country code of the phone number (required if channel is PHONE).
`email`	Conditional	User’s email (required if channel is EMAIL).
`channelType`	Conditional	Type of social login initiated (required if channel is OAUTH).

Attribute	Mandatory	Description
`statusCode`	Yes	Outcome of the request. 2xx for success, 4xx and 5xx for failures.
`success`	Yes	Boolean flag indicating request success.
`response`	Yes	Detailed response JSON containing the response details.

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

Step 5: Verify OTP

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

const verifyOTP = () => {
OTPlessSignin.verify({
  channel: "PHONE",
  phone: "98785XXXXX",
  otp: "123456",
  countryCode: "+91",
});
};

const verifyOTP = () => {
  OTPlessSignin.verify({
    channel: "EMAIL",
    email: "satyam@otpless.com",
    otp: "123456",
  });
};

🏁 Checkpoint

To ensure a smooth integration process:

Deploy your app/website with the included OTPLESS SDK.
Conduct tests to verify the sign-in flow functions correctly.
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

Validate ID Token

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

Validate Token (Opaque)

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

Web SDKs

Native/Mobile SDKs

References

Step 1: Add SDK Dependency

Step 2: Initialize SDK and Handle Callback

Step 3: Create Your UI

Step 4: Initiate Authentication

Step 5: Verify OTP

🏁 Checkpoint

User Information Response Structure

Next Steps

Validate ID Token

Validate Token (Opaque)

​Step 1: Add SDK Dependency

​Step 2: Initialize SDK and Handle Callback

​Step 3: Create Your UI

​Step 4: Initiate Authentication

​Step 5: Verify OTP

​🏁 Checkpoint

​User Information Response Structure

​Next Steps

Validate ID Token

Validate Token (Opaque)

Step 1: Add SDK Dependency

Step 2: Initialize SDK and Handle Callback

Step 3: Create Your UI

Step 4: Initiate Authentication

Step 5: Verify OTP

🏁 Checkpoint

User Information Response Structure

Next Steps