iOS SDK - OTPLESS

This page covers the SNA-only integration of the OTPless Headless SDK on iOS. The SDK accepts the requestId generated by the Create API, performs the silent network handshake, and reports progress through callbacks. Your backend confirms the final result via the Status Check API.

Requirements

Requirement	Version
iOS	13.0+
Xcode	12.0+
Swift	5.5+

Step 1: Add SDK dependency

The SDK can be installed via CocoaPods or Swift Package Manager. Find the latest version of the SDK here.

# Add to your Podfile's dependencies section
pod 'OtplessBM/Core', 'latest_version'

In Xcode, click File > Swift Packages > Add Package Dependency.
Enter the repository URL:
   https://github.com/otpless-tech/otpless-headless-iOS-sdk.git
Select the dependency rule as "exact version" and use the latest version.

For CocoaPods, run the following in your root folder to fetch the dependency:

pod repo update
pod install

Step 2: Configure Info.plist for SNA

Add the following block to your Info.plist only if you are using the SNA feature.

If the NSAppTransportSecurity key is not already present, add the entire block below.
If the NSAppTransportSecurity key is already present, add the listed domains one by one under NSExceptionDomains.

Info.plist

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>api-csp.airtel.in</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>v4-api-csp.airtel.in</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>in-vil.ipification.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>partnerapi.jio.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

Make sure Silent Network Authentication is enabled on the OTPLESS dashboard. For an SNA-only configuration, SNA must be the only channel enabled. Learn more about Silent Network Authentication.

Step 3: Start SNA with the requestId

Pass the requestId returned by the Create API to start():

otplessTask?.cancel() // Cancel any ongoing tasks to prevent request duplication

let request = OtplessRequest()
otplessRequest.set(fromBackend: "REQUEST_ID_FROM_API")

otplessTask = Task(priority: .userInitiated) {
    await Otpless.shared.start(withRequest: request)
}

Start polling the Status Check API from your backend immediately after calling start(). The SDK callback and the server status run in parallel.

Step 4: Handle callbacks

func onResponse(_ response: OtplessBM.OtplessResponse) {
    Otpless.shared.commitOtplessResponse(response)

    switch response.responseType {
    case .SDK_READY:
        // SDK initialized successfully — enable your continue button
        // or proceed with user authentication.
        print("SDK has been initialized successfully.")

    case .FAILED:
        // SDK initialization failed
        if response.statusCode == 5003 {
            print("SDK initialization failed, please try to initialize the SDK again")
        }

    case .INITIATE:
        // Authentication has been initiated
        if response.statusCode == 200 {
            let authType = response.response?["authType"] as? String
            if authType == "SILENT_AUTH" {
                // SNA is being attempted — show a loading state.
            }
        } else {
            handleInitiateError(response)
        }

    case .ONETAP:
        // Final success response with token / idToken
        if response.statusCode == 200 {
            if let data = response.response?["data"] as? [String: Any] {
                if let idToken = data["idToken"] as? String, !idToken.isEmpty {
                    // Process idToken and verify it on your backend.
                }
                if let token = data["token"] as? String, !token.isEmpty {
                    // Process token and verify it on your backend.
                }
            } else {
                print("Token not received")
            }
        } else {
            print("Token verification failed")
        }

    case .AUTH_TERMINATED:
        // SNA-only configuration: auth could not complete.
        // Emitted when pre-checks fail, or when SNA was attempted
        // and then failed/expired. Treat as a terminal failure and
        // rely on the Status Check API for the final outcome.
        break
    }
}

Callback reference

The SDK works in two steps — initialization and start() — and each step has its own set of callbacks.

Step 1: Initialization callbacks

Emitted when the SDK initializes.

Callback	Meaning
`SDK_READY`	SDK initialization completed.
`FAILED`	SDK failed to initialize (e.g. `statusCode 5003`).

Step 2: Start callbacks

Emitted after you invoke start() to begin authentication.

Callback	State	Meaning
`INITIATE`	Non-terminal	SNA is being attempted after pre-checks pass. `authType` is `SILENT_AUTH`.
`ONETAP`	Success — terminal	SNA completed successfully (Silent Mobile Verification). Returns `token` / `idToken`.
`AUTH_TERMINATED`	Failed — terminal	Emitted in two cases: (1) pre-checks failed → terminated directly; (2) SNA was initiated and then failed/expired.

For the errorCode / statusCode values surfaced in SDK callbacks, see SDK Error Codes.

Next step

Status Check API

Confirm the authoritative auth status from your server.

​Requirements

​Step 1: Add SDK dependency

​Step 2: Configure Info.plist for SNA

​Step 3: Start SNA with the requestId

​Step 4: Handle callbacks

​Callback reference

​Step 1: Initialization callbacks

​Step 2: Start callbacks

​Next step

Status Check API

Requirements

Step 1: Add SDK dependency

Step 2: Configure Info.plist for SNA

Step 3: Start SNA with the requestId

Step 4: Handle callbacks

Callback reference

Step 1: Initialization callbacks

Step 2: Start callbacks

Next step