# Capacitor Native Biometric Add Face ID, Touch ID and fingerprint login to your Capacitor app, and keep credentials safe in the iOS Keychain and Android Keystore. Capgo - Instant updates for Capacitor

Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.

➡️ Get started for free

14-day unlimited free trial. No credit card required

@capgo/capacitor-native-biometric for Capacitor apps

## Key features - **Biometric check**: `isAvailable()` returns the biometry type, with optional device credential fallback. - **Authenticate**: `verifyIdentity()` shows the native biometric prompt. - **Credentials**: `setCredentials()`, `getCredentials()`, `getSecureCredentials()` and `deleteCredentials()` per server. - **Secure data**: `setData()`, `getData()` and `getSecureData()` store any string value. - **Change events**: the `biometryChange` listener runs when the app resumes, so you can detect enrollment changes made while it was in the background. - **Platforms**: iOS, Android and Web. Web provides mocks for development. ## Why Native Biometric? A **free**, **comprehensive** biometric authentication plugin with secure credential storage: - **All biometric types** - Face ID, Touch ID, Fingerprint, Face Authentication, Iris, and Device Credentials (PIN, pattern, password) - **Secure credential storage** - Keychain (iOS) and Keystore (Android) integration - **Flexible fallback** - Optional passcode fallback when biometrics unavailable - **Customizable UI** - Full control over prompts, titles, descriptions, button text - **Detailed error codes** - Unified error handling across iOS and Android - **Resume listener** - Detect biometry availability changes when app returns from background - **Modern package management** - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8) Perfect for banking apps, password managers, authentication flows, and any app requiring secure user verification. ## Documentation The most complete doc is available here: https://capgo.app/docs/plugins/native-biometric/ ## ⚠️ Security Considerations ### Important: verifyIdentity() Can Be Bypassed on Rooted/Jailbroken Devices The `verifyIdentity()` method **should not be used as the sole authentication mechanism** for sensitive operations. On rooted Android devices or jailbroken iOS devices, attackers can use tools like Frida, Xposed, or similar frameworks to: - Hook the JavaScript bridge and force `verifyIdentity()` to return success - Intercept native method calls and bypass biometric authentication - Modify the app's runtime behavior to skip authentication checks ### Recommended Security Practices 1. **Use Root/Jailbreak Detection**: Protect your app by detecting compromised devices. We recommend using the **[@capgo/capacitor-is-root](https://github.com/Cap-go/capacitor-is-root)** plugin to detect rooted/jailbroken devices: ```typescript import { IsRoot } from '@capgo/capacitor-is-root'; async function checkDeviceSecurity() { const { result } = await IsRoot.isRooted(); if (result) { // Handle rooted device - show warning, restrict features, or block access console.warn('Device security compromised'); return false; } return true; } ``` 2. **Never Store Sensitive Data Client-Side**: Don't rely on locally stored credentials for critical authentication. Use `verifyIdentity()` as a convenience feature, not a security boundary. 3. **Server-Side Verification**: Always validate authentication on your backend server. Biometric authentication should be used for user convenience, with the real authentication happening server-side. 4. **Implement Additional Security Layers**: - Use certificate pinning for API calls - Implement server-side session management - Use short-lived tokens that expire after biometric auth - Add anti-tampering checks ### Secure Usage Pattern ```typescript import { NativeBiometric } from "@capgo/capacitor-native-biometric"; import { IsRoot } from '@capgo/capacitor-is-root'; async function secureAuthentication() { // 1. Check device security first const { result } = await IsRoot.isRooted(); if (result) { // Handle rooted device appropriately // Example: showSecurityWarning() could display an alert to the user showSecurityWarning(); // Optionally: disable biometric login, require re-authentication, etc. } // 2. Perform biometric authentication try { await NativeBiometric.verifyIdentity({ reason: "Authenticate to access your account", title: "Biometric Login", }); } catch (error) { console.error("Biometric authentication failed"); return false; } // 3. Get stored credentials (if needed for convenience) const credentials = await NativeBiometric.getCredentials({ server: "www.example.com", }); // 4. CRITICAL: Validate credentials with your backend server // Example: validateWithServer() should send credentials to your API // and verify them server-side before granting access const isValid = await validateWithServer(credentials.username, credentials.password); return isValid; } ``` ### What This Plugin Provides This plugin provides: - ✅ Convenient local biometric authentication UI - ✅ Secure credential storage using Keychain (iOS) and Keystore (Android) - ✅ Protection against casual unauthorized access This plugin does NOT provide: - ❌ Protection against determined attackers on compromised devices - ❌ Server-side authentication or validation - ❌ Root/jailbreak detection (use [@capgo/capacitor-is-root](https://github.com/Cap-go/capacitor-is-root)) ### Recent Security Improvements (v8.2.0+) **Android Encryption Enhancement**: The Android implementation now uses properly randomized Initialization Vectors (IVs) for AES-GCM encryption of stored credentials. Previous versions used a fixed IV, which is a cryptographic vulnerability. **Automatic Migration**: The plugin automatically handles credentials encrypted with the older method: - When reading credentials, it first attempts the new secure format, then falls back to the legacy format if needed - When saving credentials, they are always encrypted using the new secure format - No action required from users - migration happens transparently on first credential save after update **Recommendation**: After updating to v8.2.0+, users should re-save their credentials to ensure they're encrypted with the improved format. This happens automatically when users authenticate and save credentials again. ## Compatibility | Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.\*.\* | v8.\*.\* | ✅ | | v7.\*.\* | v7.\*.\* | On demand | | v6.\*.\* | v6.\*.\* | ❌ | | v5.\*.\* | v5.\*.\* | ❌ | > **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained. ## Installation (Only supports Capacitor 7) You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command: ```bash npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins ``` Then use the following prompt: ```text Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project. ``` If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below: - `npm i @capgo/capacitor-native-biometric` ## Usage ⚠️ **Important**: Before implementing biometric authentication, review the [Security Considerations](#️-security-considerations) section to understand limitations and best practices for secure implementation. ```ts import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric"; async performBiometricVerification(){ const result = await NativeBiometric.isAvailable(); if(!result.isAvailable) return; // Check the biometry type for display purposes // IMPORTANT: Always use isAvailable for logic decisions, not biometryType const isFaceID = result.biometryType == BiometryType.FACE_ID; // Check if device has PIN/pattern/password set console.log('Device is secure:', result.deviceIsSecure); // Check if strong biometry (Face ID, Touch ID, fingerprint) is available console.log('Strong biometry available:', result.strongBiometryIsAvailable); const verified = await NativeBiometric.verifyIdentity({ reason: "For easy log in", title: "Log in", subtitle: "Maybe add subtitle here?", description: "Maybe a description too?", }) .then(() => true) .catch(() => false); if(!verified) return; const credentials = await NativeBiometric.getCredentials({ server: "www.example.com", }); // IMPORTANT: Always validate credentials with your backend server // Do not trust client-side verification alone } // Save user's credentials NativeBiometric.setCredentials({ username: "username", password: "password", server: "www.example.com", }).then(); // Check if credentials are already saved const isSaved = await NativeBiometric.isCredentialsSaved({ server: "www.example.com", }); console.log('Credentials saved:', isSaved.isSaved); // Delete user's credentials NativeBiometric.deleteCredentials({ server: "www.example.com", }).then(); // Listen for biometry availability changes when app resumes from background const handle = await NativeBiometric.addListener('biometryChange', (result) => { console.log('Biometry availability changed:', result.isAvailable); console.log('Biometry type:', result.biometryType); }); // To remove the listener when no longer needed: // await handle.remove(); ``` ### Complete Login Flow Example This example shows how to use `isCredentialsSaved()` to check if credentials are already saved before showing a "save credentials" popup: ```ts // After successful login async handleLoginSuccess(username: string, password: string) { // Check if biometric authentication is available const result = await NativeBiometric.isAvailable({ useFallback: true }); if (!result.isAvailable) { // Biometrics not available - go to home page directly this.navigateToHome(); return; } // Check if credentials are already saved const checkCredentials = await NativeBiometric.isCredentialsSaved({ server: "www.example.com" }); if (checkCredentials.isSaved) { // Credentials already saved - go to home page this.navigateToHome(); } else { // No credentials saved - show save credentials popup this.showSaveCredentialsPopup(username, password); } } // Save credentials when user confirms async saveCredentials(username: string, password: string) { await NativeBiometric.setCredentials({ username: username, password: password, server: "www.example.com", }); this.navigateToHome(); } ``` ### Biometric Auth Errors This is a plugin specific list of error codes that can be thrown on `verifyIdentity()` failure, set as part of `isAvailable()`, or returned from `getSecureCredentials()` and `getSecureData()` when no biometric-protected item exists for the requested server or key. It consolidates Android and iOS specific authentication error codes into one combined error list. | Code | Description | Platform | | ---- | -------------------------------- | ---------------------------- | | 0 | Unknown Error | Android, iOS | | 1 | Biometrics Unavailable | Android, iOS | | 2 | User Lockout | Android, iOS | | 3 | Biometrics Not Enrolled | Android, iOS | | 4 | User Temporary Lockout | Android (Lockout for 30sec) | | 10 | Authentication Failed | Android, iOS | | 11 | App Cancel | iOS | | 12 | Invalid Context | iOS | | 13 | Not Interactive | iOS | | 14 | Passcode Not Set | Android, iOS | | 15 | System Cancel | Android, iOS | | 16 | User Cancel | Android, iOS | | 17 | User Fallback | Android, iOS | | 21 | No Protected Credentials/Data Found | Android, iOS | **Code 21 (`getSecureCredentials`, `getSecureData`)**, Stable, expected rejection when no biometric-protected credentials or data exist (for example after deletion, a fresh install, or items invalidated by biometric enrollment changes). Platform messages differ slightly: - **`getSecureCredentials()`** - **Android:** `No protected credentials found` - **iOS:** `No protected credentials found for server` - **`getSecureData()`** - **Android:** `No protected data found` - **iOS:** `No protected data found for key` `isCredentialsSaved()` and `isDataSaved()` return true when any credentials or data exist for the server or key (protected or unprotected), so they do not guarantee that `getSecureCredentials()` or `getSecureData()` will succeed. Handle code `21` in your catch block, or only call after storing with `accessControl` BIOMETRY_CURRENT_SET or BIOMETRY_ANY. See [`getSecureCredentials()`](#getsecurecredentials) and [`getSecureData()`](#getsecuredata) for details. * [`isAvailable(...)`](#isavailable) * [`addListener('biometryChange', ...)`](#addlistenerbiometrychange-) * [`verifyIdentity(...)`](#verifyidentity) * [`getCredentials(...)`](#getcredentials) * [`setCredentials(...)`](#setcredentials) * [`deleteCredentials(...)`](#deletecredentials) * [`getSecureCredentials(...)`](#getsecurecredentials) * [`isCredentialsSaved(...)`](#iscredentialssaved) * [`setData(...)`](#setdata) * [`getData(...)`](#getdata) * [`getSecureData(...)`](#getsecuredata) * [`deleteData(...)`](#deletedata) * [`isDataSaved(...)`](#isdatasaved) * [`getPluginVersion()`](#getpluginversion) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### isAvailable(...) ```typescript isAvailable(options?: IsAvailableOptions | undefined) => Promise ``` Checks if biometric authentication hardware is available. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | IsAvailableOptions | **Returns:** Promise<AvailableResult> **Since:** 1.0.0 -------------------- ### addListener('biometryChange', ...) ```typescript addListener(eventName: 'biometryChange', listener: BiometryChangeListener) => Promise ``` Adds a listener that is called when the app resumes from background. This is useful to detect if biometry availability has changed while the app was in the background (e.g., user enrolled/unenrolled biometrics). | Param | Type | Description | | --------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **`eventName`** | 'biometryChange' | - Must be 'biometryChange' | | **`listener`** | BiometryChangeListener | - Callback function that receives the updated AvailableResult | **Returns:** Promise<PluginListenerHandle> **Since:** 7.6.0 -------------------- ### verifyIdentity(...) ```typescript verifyIdentity(options?: BiometricOptions | undefined) => Promise ``` Prompts the user to authenticate with biometrics. | Param | Type | | ------------- | ------------------------------------------------------------- | | **`options`** | BiometricOptions | **Since:** 1.0.0 -------------------- ### getCredentials(...) ```typescript getCredentials(options: GetCredentialOptions) => Promise ``` Gets the stored credentials for a given server. | Param | Type | | ------------- | --------------------------------------------------------------------- | | **`options`** | GetCredentialOptions | **Returns:** Promise<Credentials> **Since:** 1.0.0 -------------------- ### setCredentials(...) ```typescript setCredentials(options: SetCredentialOptions) => Promise ``` Stores the given credentials for a given server. | Param | Type | | ------------- | --------------------------------------------------------------------- | | **`options`** | SetCredentialOptions | **Since:** 1.0.0 -------------------- ### deleteCredentials(...) ```typescript deleteCredentials(options: DeleteCredentialOptions) => Promise ``` Deletes the stored credentials for a given server. | Param | Type | | ------------- | --------------------------------------------------------------------------- | | **`options`** | DeleteCredentialOptions | **Since:** 1.0.0 -------------------- ### getSecureCredentials(...) ```typescript getSecureCredentials(options: GetSecureCredentialsOptions) => Promise ``` Gets the stored credentials for a given server, requiring biometric authentication. Credentials must have been stored with accessControl set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY. On iOS, the system automatically shows the biometric prompt when accessing the protected Keychain item. On Android, BiometricPrompt is shown with a CryptoObject bound to the credential decryption key. If no protected credentials exist for the server, the promise rejects with code `21` (`BiometricAuthError.NO_PROTECTED_CREDENTIALS_FOUND`). This is stable, expected behavior — for example when credentials were never saved with biometric protection, were deleted, or were invalidated after biometric enrollment changes. `isCredentialsSaved()` returns true when any credentials (protected or unprotected) exist, so it does not guarantee a biometric-protected entry is present — handle code `21` in your catch block or only call after storing with `accessControl` BIOMETRY_CURRENT_SET or BIOMETRY_ANY. Platform messages: Android `No protected credentials found`, iOS `No protected credentials found for server`. | Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | **`options`** | GetSecureCredentialsOptions | **Returns:** Promise<Credentials> **Since:** 8.4.0 -------------------- ### isCredentialsSaved(...) ```typescript isCredentialsSaved(options: IsCredentialsSavedOptions) => Promise ``` Checks if credentials are already saved for a given server. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | IsCredentialsSavedOptions | **Returns:** Promise<IsCredentialsSavedResult> **Since:** 7.3.0 -------------------- ### setData(...) ```typescript setData(options: SetDataOptions) => Promise ``` Stores an arbitrary string value under the given key. Values are encrypted at rest using the platform secure storage backend (Android Keystore + SharedPreferences, iOS Keychain). For biometric-protected storage, set `accessControl` and retrieve the value with `getSecureData()`. Credential helpers remain available for username/password flows. | Param | Type | | ------------- | --------------------------------------------------------- | | **`options`** | SetDataOptions | **Since:** 8.6.0 -------------------- ### getData(...) ```typescript getData(options: GetDataOptions) => Promise ``` Gets a previously stored value for the given key. Only returns values stored without biometric `accessControl`. | Param | Type | | ------------- | --------------------------------------------------------- | | **`options`** | GetDataOptions | **Returns:** Promise<StoredData> **Since:** 8.6.0 -------------------- ### getSecureData(...) ```typescript getSecureData(options: GetSecureDataOptions) => Promise ``` Gets a biometric-protected value for the given key. The value must have been stored with `accessControl` set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY. | Param | Type | | ------------- | --------------------------------------------------------------------- | | **`options`** | GetSecureDataOptions | **Returns:** Promise<StoredData> **Since:** 8.6.0 -------------------- ### deleteData(...) ```typescript deleteData(options: DeleteDataOptions) => Promise ``` Deletes the stored value for the given key (protected and unprotected). | Param | Type | | ------------- | --------------------------------------------------------------- | | **`options`** | DeleteDataOptions | **Since:** 8.6.0 -------------------- ### isDataSaved(...) ```typescript isDataSaved(options: IsDataSavedOptions) => Promise ``` Checks whether a value is already saved for the given key. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | IsDataSavedOptions | **Returns:** Promise<IsDataSavedResult> **Since:** 8.6.0 -------------------- ### getPluginVersion() ```typescript getPluginVersion() => Promise<{ version: string; }> ``` Get the native Capacitor plugin version. **Returns:** Promise<{ version: string; }> **Since:** 1.0.0 -------------------- ### Interfaces #### AvailableResult Result from isAvailable() method indicating biometric authentication availability. | Prop | Type | Description | | ------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`isAvailable`** | boolean | Whether authentication is available. On Android, weak-only biometrics (such as some face unlock implementations) are available for `verifyIdentity()` when no `allowedBiometryTypes` filter excludes them. If `useFallback` is true, PIN/pattern/password can also make this value true. | | **`authenticationStrength`** | AuthenticationStrength | The strength of available authentication method (STRONG, WEAK, or NONE) | | **`biometryType`** | BiometryType | The primary biometry type available on the device. On Android devices with multiple biometry types, this returns MULTIPLE. Use this for display purposes only - always use isAvailable for logic decisions. | | **`deviceIsSecure`** | boolean | Whether the device has a secure lock screen (PIN, pattern, or password). This is independent of biometric enrollment. | | **`strongBiometryIsAvailable`** | boolean | Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong) is specifically available, separate from weak biometry or device credentials. | | **`errorCode`** | BiometricAuthError | Error code from BiometricAuthError enum. Only present when isAvailable is false. Indicates why biometric authentication is not available. | #### IsAvailableOptions | Prop | Type | Description | Default | Since | | -------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | **`useFallback`** | boolean | Whether passcode or device credentials should count toward biometric availability when no biometric is enrolled or available. - On iOS, this affects both `isAvailable()` and `verifyIdentity()`. - On Android, this is honored by `isAvailable()` only — the native check computes `fallbackAvailable = useFallback && deviceIsSecure` and reports availability accordingly. The `verifyIdentity()` flow ignores this option on Android due to BiometricPrompt API constraints (DEVICE_CREDENTIAL authenticator and negative button are mutually exclusive); use `BiometricOptions.useFallback` (iOS-only) to control the auth-dialog fallback there. | | | | **`preferMultipleBiometryType`** | boolean | Android only. Report `BiometryType.MULTIPLE` whenever a fingerprint is enrolled and the device also advertises a face or iris sensor, even when that second modality cannot be confirmed as enrolled. You normally do not need this. On Android 12 and newer a face enrolled next to a fingerprint is usually detected and reported as `BiometryType.MULTIPLE` on its own. Detection is best-effort, and is not possible on Android 11 and older, for the rare Class 3 (Strong) face sensor, or on a vendor build whose biometric labels name only the preferred modality. Undetected devices report `BiometryType.FINGERPRINT`, because most devices advertise a face sensor the user never enrolled. Set this to `true` if your UI would rather over-report `MULTIPLE` there. `verifyIdentity()` is unaffected and still offers every enrolled biometric the device supports; this only changes the reported type. The most recent value is reused for `biometryChange` events. | false | 8.6.5 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | #### BiometricOptions | Prop | Type | Description | Default | | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | **`reason`** | string | | | | **`title`** | string | | | | **`subtitle`** | string | | | | **`description`** | string | | | | **`negativeButtonText`** | string | | | | **`useFallback`** | boolean | Only for iOS. Specifies if should fallback to passcode authentication if biometric authentication fails. On Android, this parameter is ignored due to BiometricPrompt API constraints: DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive. | | | **`fallbackTitle`** | string | Only for iOS. Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system. | | | **`maxAttempts`** | number | Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5. | 1 | | **`allowedBiometryTypes`** | BiometryType[] | Only for Android. Specify which biometry types are allowed for authentication. If not specified, all enrolled biometric classes (strong and weak) are allowed. On Android, face unlock is often classified as weak biometrics — include `BiometryType.FACE_AUTHENTICATION` or omit this option to allow it. Use `BiometryType.DEVICE_CREDENTIAL` for PIN/pattern/password (disables the cancel button). | | #### Credentials | Prop | Type | | -------------- | ------------------- | | **`username`** | string | | **`password`** | string | #### GetCredentialOptions | Prop | Type | | ------------ | ------------------- | | **`server`** | string | #### SetCredentialOptions | Prop | Type | Description | Default | Since | | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------ | | **`username`** | string | | | | | **`password`** | string | | | | | **`server`** | string | | | | | **`accessControl`** | AccessControl | Access control level for the stored credentials. When set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY, the credentials are hardware-protected and require biometric authentication to access. On iOS, this adds SecAccessControl to the Keychain item. On Android, this creates a biometric-protected Keystore key and requires BiometricPrompt authentication for both storing and retrieving credentials. | AccessControl.NONE | 8.4.0 | | **`authValidityDuration`** | number | Only for Android. Ignored on iOS and web. Only meaningful together with `accessControl` set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY. Number of seconds a successful biometric authentication remains valid for Keystore key use. When `0` or omitted (the default), the Keystore key requires a fresh authentication for every operation — each `getSecureCredentials()` call shows a `BiometricPrompt` cryptographically bound to that specific read via a `CryptoObject`. This is the strongest mode: it guarantees no code path can use the key without a live biometric check. When set to a value greater than `0`, one successful biometric authentication authorizes Keystore key use for that many seconds. Subsequent `getSecureCredentials()` calls within the window succeed without showing a prompt. This trades security for convenience: any in-app code that can reach the decryption call — not just the code path that triggered the prompt — can silently read the credentials for the remainder of the window. | 0 | 8.5.0 | | **`title`** | string | Title for the biometric prompt shown while protecting credentials. Only for Android. | "Protect Credentials" | 8.4.14 | | **`negativeButtonText`** | string | Text for the negative/cancel button in the biometric prompt. Only for Android. | "Cancel" | 8.4.14 | | **`maxAttempts`** | number | Set a maximum number of attempts for biometric authentication. The maximum allowed by Android is 5. Only for Android. | 1 | | #### DeleteCredentialOptions | Prop | Type | | ------------ | ------------------- | | **`server`** | string | #### GetSecureCredentialsOptions | Prop | Type | Description | Default | | ------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- | | **`server`** | string | | | | **`reason`** | string | Explanation text shown as the subtitle of the Touch ID prompt. Face ID does not display it. Only for iOS. | | | **`title`** | string | Title for the biometric prompt. Only for Android. | | | **`subtitle`** | string | Subtitle for the biometric prompt. Only for Android. | | | **`description`** | string | Description for the biometric prompt. Only for Android. | | | **`negativeButtonText`** | string | Text for the negative/cancel button. Only for Android. | | | **`maxAttempts`** | number | Set a maximum number of attempts for biometric authentication. The maximum allowed by Android is 5. Only for Android. | 1 | #### IsCredentialsSavedResult | Prop | Type | | ------------- | -------------------- | | **`isSaved`** | boolean | #### IsCredentialsSavedOptions | Prop | Type | | ------------ | ------------------- | | **`server`** | string | #### SetDataOptions | Prop | Type | Description | Default | Since | | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----- | | **`key`** | string | Unique identifier for the stored value. Use a stable app-specific namespace (e.g. `pin`, `session.token`). | | | | **`value`** | string | Arbitrary string payload. Serialize objects with `JSON.stringify()` before storing. Platform limits apply: Android Keystore-backed encryption works best with payloads under ~8 KB; iOS Keychain practical limits are higher but very large values are discouraged. | | | | **`accessControl`** | AccessControl | Access control level for the stored value. When set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY, the value is hardware-protected and requires biometric authentication to access via `getSecureData()`. | AccessControl.NONE | 8.6.0 | | **`authValidityDuration`** | number | Only for Android. Ignored on iOS and web. Only meaningful together with `accessControl` set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY. | 0 | 8.6.0 | | **`title`** | string | Title for the biometric prompt shown while protecting data. Only for Android. | "Protect Data" | 8.6.0 | | **`negativeButtonText`** | string | Text for the negative/cancel button in the biometric prompt. Only for Android. | "Cancel" | 8.6.0 | | **`maxAttempts`** | number | Set a maximum number of attempts for biometric authentication. The maximum allowed by Android is 5. Only for Android. | 1 | | #### StoredData | Prop | Type | | ----------- | ------------------- | | **`value`** | string | #### GetDataOptions | Prop | Type | | --------- | ------------------- | | **`key`** | string | #### GetSecureDataOptions | Prop | Type | Description | Default | | ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | **`key`** | string | | | | **`reason`** | string | Explanation text shown as the subtitle of the Touch ID prompt. Face ID does not display it. Only for iOS. | | | **`title`** | string | Title for the biometric prompt. Only for Android. | | | **`subtitle`** | string | Subtitle for the biometric prompt. Only for Android. | | | **`description`** | string | Description for the biometric prompt. Only for Android. | | | **`negativeButtonText`** | string | Text for the negative/cancel button. Only for Android. | | | **`fallbackTitle`** | string | Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system. Set it to an empty string to hide the button. Only for iOS. | | | **`maxAttempts`** | number | Set a maximum number of attempts for biometric authentication. The maximum allowed by Android is 5. Only for Android. | 1 | #### DeleteDataOptions | Prop | Type | | --------- | ------------------- | | **`key`** | string | #### IsDataSavedResult | Prop | Type | | ------------- | -------------------- | | **`isSaved`** | boolean | #### IsDataSavedOptions | Prop | Type | | --------- | ------------------- | | **`key`** | string | ### Type Aliases #### BiometryChangeListener Callback type for biometry change listener (result: AvailableResult): void ### Enums #### AuthenticationStrength | Members | Value | Description | | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`NONE`** | 0 | No authentication available, even if PIN is available but useFallback = false | | **`STRONG`** | 1 | Strong authentication: Face ID on iOS, fingerprints on devices that consider fingerprints strong (Android). Note: PIN/pattern/password is NEVER considered STRONG, even when useFallback = true. | | **`WEAK`** | 2 | Weak authentication: Face authentication on Android devices that consider face weak, or PIN/pattern/password if useFallback = true (PIN is always WEAK, never STRONG). | #### BiometryType | Members | Value | | ------------------------- | -------------- | | **`NONE`** | 0 | | **`TOUCH_ID`** | 1 | | **`FACE_ID`** | 2 | | **`FINGERPRINT`** | 3 | | **`FACE_AUTHENTICATION`** | 4 | | **`IRIS_AUTHENTICATION`** | 5 | | **`MULTIPLE`** | 6 | | **`DEVICE_CREDENTIAL`** | 7 | #### BiometricAuthError | Members | Value | Description | Since | | ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`UNKNOWN_ERROR`** | 0 | Unknown error occurred | | | **`BIOMETRICS_UNAVAILABLE`** | 1 | Biometrics are unavailable (no hardware or hardware error) Platform: Android, iOS | | | **`USER_LOCKOUT`** | 2 | User has been locked out due to too many failed attempts Platform: Android, iOS | | | **`BIOMETRICS_NOT_ENROLLED`** | 3 | No biometrics are enrolled on the device Platform: Android, iOS | | | **`USER_TEMPORARY_LOCKOUT`** | 4 | User is temporarily locked out (Android: 30 second lockout) Platform: Android | | | **`AUTHENTICATION_FAILED`** | 10 | Authentication failed (user did not authenticate successfully) Platform: Android, iOS | | | **`APP_CANCEL`** | 11 | App canceled the authentication (iOS only) Platform: iOS | | | **`INVALID_CONTEXT`** | 12 | Invalid context (iOS only) Platform: iOS | | | **`NOT_INTERACTIVE`** | 13 | Authentication was not interactive (iOS only) Platform: iOS | | | **`PASSCODE_NOT_SET`** | 14 | Passcode/PIN is not set on the device Platform: Android, iOS | | | **`SYSTEM_CANCEL`** | 15 | System canceled the authentication (e.g., due to screen lock) Platform: Android, iOS | | | **`USER_CANCEL`** | 16 | User canceled the authentication Platform: Android, iOS | | | **`USER_FALLBACK`** | 17 | User chose to use fallback authentication method Platform: Android, iOS | | | **`NO_PROTECTED_CREDENTIALS_FOUND`** | 21 | No biometric-protected credentials or data exist for the requested server or key. Platform: Android, iOS (`getSecureCredentials()`, `getSecureData()`). Thrown when `getSecureCredentials()` or `getSecureData()` is called but nothing was stored with `accessControl` BIOMETRY_CURRENT_SET or BIOMETRY_ANY — for example after deletion, a fresh install, or items removed from the secure enclave after biometric enrollment changes. Rejection message differs by platform and method: - `getSecureCredentials()`: Android `No protected credentials found`, iOS `No protected credentials found for server` - `getSecureData()`: Android `No protected data found`, iOS `No protected data found for key` | 8.4.0 | #### AccessControl | Members | Value | Description | | -------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`NONE`** | 0 | No biometric protection. Credentials are accessible without authentication. This is the default behavior for backward compatibility. | | **`BIOMETRY_CURRENT_SET`** | 1 | Biometric authentication required for credential access. Credentials are invalidated if biometrics change (e.g., new fingerprint enrolled). More secure but credentials are lost if user modifies their biometric enrollment. | | **`BIOMETRY_ANY`** | 2 | Biometric authentication required for credential access. Credentials survive new biometric enrollment (e.g., adding a new fingerprint). More lenient — recommended for most apps. | ## Face ID (iOS) To use FaceID Make sure to provide a value for NSFaceIDUsageDescription, otherwise your app may crash on iOS devices with FaceID. This value is just the reason for using FaceID. You can add something like the following example to App/info.plist: ```xml NSFaceIDUsageDescription For an easier and faster log in. ``` ## Biometric (Android) To use android's BiometricPrompt api you must add the following permission to your AndroidManifest.xml: ```xml ``` ### Important Note About biometryType on Android The `biometryType` field indicates what biometric hardware is present, but **hardware presence does not guarantee availability**. Some Android devices report face authentication hardware but don't make it available to apps. **Always use `isAvailable` for logic decisions**, not `biometryType`. The `biometryType` field should only be used for display purposes (e.g., showing "Use Face ID" vs "Use Fingerprint" in your UI). ## Web Platform This plugin provides a dummy implementation for in-browser development and testing. On web: - `isAvailable()` returns `{ isAvailable: true, ... }` simulating biometric availability - `addListener()` returns a no-op handle - `verifyIdentity()` always succeeds (no actual authentication) - Credential methods use in-memory storage (credentials stored in a Map, cleared on page refresh) This allows you to develop and test your app in the browser without errors. Note that real biometric authentication is only available on iOS and Android platforms. ## Contributors [Jonthia](https://github.com/jonthia) [QliQ.dev](https://github.com/qliqdev) [Brian Weasner](https://github.com/brian-weasner) [Mohamed Diarra](https://github.com/mohdiarra) ### Want to Contribute? Learn about contributing [HERE](./CONTRIBUTING.md) ## Notes Hasn't been tested on Android API level 22 or lower.