OTPless Passkey API Integration Guide

Prerequisite

Navigate to Dev Settings

Once logged in, navigate to Dev Settings in the left menu.

Copy Credentials

Copy the clientId, clientSecret, and appId.

Contact OTPless Team

Please contact the OTPless team to activate passkey functionality for your account.

Workflow

Initialize Passkey Identity

Use the initiate WebAuthn API to create the requestId.

Initiate Login via SDK

Pass the requestId to the OTPless SDK, which will handle the Passkey-based login flow.

Complete Authentication

The OTPless SDK validates the user’s authentication and notifies your system upon successful login or registration, providing a token.

Validate the Token

Use the validate token API to verify the authentication token.

Demo Link: Passkey Demo

1. Initiate API

The OTPless Passkey initiate API allows merchants to generate requestId for a particular user identity.

API Endpoint

POST https://auth.otpless.app/auth/v1/webauthn

Headers

clientId

string

required

Unique identifier for the merchant’s application.

clientSecret

string

required

Secret key associated with the clientId.

Content-Type

string

default: "application/json"

Specifies JSON format.

Body

The request body must be a JSON object with the following fields:

identityType

string

required

Specifies the type of identity. Options: PHONE_NUMBER, EMAIL, CUSTOM.

identityValue

string

required

The actual value for the specified identityType, e.g., the user’s phone number, email address, or user ID.

rpName

string

required

The name of the Relying Party (merchant) initiating the WebAuthn request.

domain

string

required

The merchant’s application domain where Passkey is implemented.

userDisplayName

string

required

The display name of the user initiating the request, typically used for personalization purposes.

attachment

string

Specifies the attachment type. Options: ALL, PLATFORM, CROSS_PLATFORM. If isSPC is true, this will always be set to PLATFORM.

ALL: The user has the option to authenticate with either a QR code (if the key is stored on a different device) or with the key stored on the same device.
PLATFORM: The user can authenticate only if the key is stored on the same device.
CROSS_PLATFORM: The user can authenticate only by scanning a QR code to use a key stored on another device.

isRegistration

boolean

Indicates whether the request is for a registration flow (true). Don’t pass this key if you want a normal login or registration flow. Useful in case you want to enforce registration (for example: Registration of a new device).

isSPC

boolean

Indicates if Secure Payment Confirmation (SPC) is required.

spc

object

Secure Payment Confirmation details (required if isSPC is true).

instrumentDisplayName

string

required

Display name of the payment instrument.

instrumentDisplayIcon

string

required

URL of the payment instrument icon. Must be HTTPS and publicly accessible.

payeeOrigin

string

required

Origin of the payee, usually the merchant’s website. Must be a URL with HTTPS scheme.

amount

number

required

Payment amount.

currency

string

required

Currency code in ISO format (e.g., INR).

If isSPC is true, the spc object is mandatory, otherwise it can be omitted.

Response

requestId

string

required

A unique identifier for the session initiation request.

Sample

Error Codes

The following error codes and responses help merchants handle errors during integration:

Status Code	Message	Error Code	Description	Solution
400	Bad Request	7134	Invalid syntax or missing parameters for RP name	Verify the `rpName` format and ensure it’s valid.
400	Bad Request	7135	Invalid domain	Check and correct the `domain` parameter.
400	Bad Request	7131	Invalid identity type	Ensure `identityType` is `PHONE_NUMBER`, `EMAIL`, or `CUSTOM`.
400	Bad Request	7133	Invalid identity value	Verify the format and value of `identityValue`.
400	Bad Request	7140	`spc` object missing or invalid when `isSPC` is true	Ensure `spc` object is provided and valid if `isSPC` is true.
401	Unauthorized	-	Invalid or missing authentication credentials	Confirm `clientId` and `clientSecret` are valid.
403	Forbidden	-	Insufficient permissions	Check if the API key has the required permissions.
404	Not Found	-	Endpoint URL typo or resource does not exist	Verify the endpoint URL and resource.
429	Too Many Requests	-	Exceeding API rate limits	Reduce request frequency or use exponential backoff.
500	Internal Server Error	-	Server issues	Retry. Contact support if the issue persists.
503	Service Unavailable	-	Server overload or maintenance	Retry after a delay. Check the Status Page for issues.

2. Initiate OTPless SDK with `requestId`

To initiate the OTPless SDK, include the following code snippet on your web page to load the SDK and use it to trigger the passkey authentication flow.

Step 1: Include the OTPless SDK Script

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

Replace YOUR_APP_ID with your actual application ID.

Step 2: Define the Callback Function

The callback function is used to handle the response after authentication. This function will receive user information and can be used to implement any custom logic.

<script>
  const callback = (userinfo) => {
    const token = userinfo.token;
    console.log(userinfo);

    // Implement your custom logic here.
  };

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

Step 3: Initiate Passkey with `requestId`

Below is the code to initiate the Passkey flow using the OTPless SDK with a specific requestId obtained from the identity creation API.

async function initiateWebAuthn() {
    const request = {
        channel: "WEB_AUTHN",
        requestId: "unique_request_id" // Replace with your actual request ID
    };

    const initiate = await OTPlessSignin.initiate({
        requestType: "initiate",
        request
    });
}

In this code:

The channel is set to "WEB_AUTHN".
Replace "unique_request_id" with the actual requestId obtained from the initiate API.
Use the initiate method from the OTPless SDK to trigger the authentication flow.

3. Validate Token API

This endpoint validates an authentication token and retrieves user identity, authentication status, network, and device information associated with the token.

API Endpoint

POST https://auth.otpless.app/auth/v1/validate/token

Headers

clientId

string

required

Unique identifier for the merchant’s application.

clientSecret

string

required

Secret key associated with the clientId.

Content-Type

string

default: "application/json"

Specifies JSON format.

Body

token

string

required

The authentication token to be validated.

Response

token

string

required

The validated token.

status

string

required

Status of the validation, e.g., “SUCCESS”.

userId

string

required

Unique identifier for the user.

timestamp

string

required

The timestamp when the validation occurred.

identities

array

required

List of user identity objects.

identityType

string

required

Type of identity, e.g., “CUSTOM”.

identityValue

string

required

Value of the identity (e.g., user ID).

channel

string

required

The channel will be “WEBAUTHN”.

verified

boolean

required

Whether the identity was verified.

verifiedAt

string

required

Timestamp of verification.

type

string

required

Type of identity operation; can be “LOGIN” or “REGISTRATION”.

network

object

Network details of the user’s location.

deviceInfo

object

Information about the user’s device, browser, and connection.

​Prerequisite

​Workflow

​1. Initiate API

​API Endpoint

​Headers

​Body

​Response

​Sample

​Error Codes

​2. Initiate OTPless SDK with requestId

​Step 1: Include the OTPless SDK Script

​Step 2: Define the Callback Function

​Step 3: Initiate Passkey with requestId

​3. Validate Token API

​API Endpoint

​Headers

​Body

​Response

​Sample

Prerequisite

Workflow

1. Initiate API

API Endpoint

Headers

Body

Response

Sample

Error Codes

2. Initiate OTPless SDK with `requestId`

Step 1: Include the OTPless SDK Script

Step 2: Define the Callback Function

Step 3: Initiate Passkey with `requestId`

3. Validate Token API

API Endpoint

Headers

Body

Response

Sample