> ## Documentation Index
> Fetch the complete documentation index at: https://otpless.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SIM Binding

> Detect SIM swaps after a successful authentication on the Android Headless SDK.

SIM binding lets you tell whether the SIM currently in the device is the same one that was used during the last successful authentication. Use it to gate sensitive actions (payments, profile changes) or to force re-auth after a SIM swap.

Available from `otpless-headless-sdk` **v2.1.0**. The feature is opt-in and disabled by default.

## How it works

After a successful **Silent Network Authentication (SNA)** or **SMS OTP auto-read**, the SDK records a fingerprint and stores it into encrypted storage. `checkSimBindingStatus()` compares that fingerprint against the current SIM and returns `true` only when they match.

The binding is written and cleared automatically:

| Outcome | Effect |
| - | - |
| Successful ONETAP where the identity is marked SIM-bound | Binding saved |
| Successful ONETAP where the identity is **not** marked SIM-bound | Any existing binding cleared |
| SIM slot cannot be resolved, or an exception occurs while saving | Any existing binding cleared |
| Encrypted storage unavailable on the device | No-op (all APIs return `false`) |

## Enable SIM binding

Set the toggle once, before starting authentication:

```kotlin theme={null}
import com.otpless.v2.android.sdk.main.OtplessSDK

OtplessSDK.isSimBindingEnabled = true
```

## Check binding status

`checkSimBindingStatus` can be called **without** first calling `OtplessSDK.initialize` — pass an application `Context` directly.

```kotlin theme={null}
lifecycleScope.launch(Dispatchers.IO) {
    val isSameSim = OtplessSDK.checkSimBindingStatus(applicationContext)
    if (isSameSim) {
        // SIM matches the one used at last successful auth — proceed.
    } else {
        // No binding, SIM swapped, device changed, or storage unavailable — re-authenticate.
    }
}
```

Returns `true` only when a binding is stored and the current SIM matches it. Any exception is swallowed and the call returns `false`.

## Clear the binding

Call after logout, account deletion, or whenever the user should be forced through a full auth again. Also callable without `initialize`.

```kotlin theme={null}
lifecycleScope.launch(Dispatchers.IO) {
    OtplessSDK.clearSimBinding(applicationContext)
}
```

## API summary

| Member | Type | Notes |
| - | - | - |
| `OtplessSDK.isSimBindingEnabled` | `var Boolean` | Default `false`. Must be `true` for the SDK to save bindings. |
| `OtplessSDK.checkSimBindingStatus(context)` | `suspend` | Returns `Boolean`. Callable without `initialize`. |
| `OtplessSDK.clearSimBinding(context)` | `suspend` | Deletes the stored binding. Callable without `initialize`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.