--- title: Capacitor Biometrics Plugin for Android & iOS description: Capacitor Biometrics plugin to request biometric authentication, such as Face ID, fingerprint, and device credential auth for Android and iOS. tags: - Insiders - Android - iOS search: boost: 2 faq: true github_repo: capawesome-team/capacitor-plugins --- # Capacitor Biometrics Plugin Capacitor plugin to request biometric authentication, such as using face recognition or fingerprint recognition.
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features The Capacitor Biometrics plugin is one of the most complete biometric authentication solutions for Capacitor apps. Here are some of the key features: - 🖥️ **Cross-platform**: Supports Android, iOS and Web. - 👁️ **Fingerprint, Face and Iris**: Supports fingerprint, face and iris recognition. - 🔑 **Device Credential**: Optionally allow the user to authenticate using their device's credential (e.g., PIN, password) if biometric authentication is not available or fails. - 🚨 **Error Codes**: Provides detailed error codes for better error handling. - ✨ **Customizable**: Customize the authentication prompt with a title, subtitle, and button text. - 🤝 **Compatibility**: Compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) and [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugins. - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. - 🔁 **Up-to-date**: Always supports the latest Capacitor version. - ⭐️ **Support**: Priority support from the Capawesome Team. - ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The Biometrics plugin is typically used whenever an app needs to verify the identity of the user, for example: - **App lock**: Require fingerprint or face authentication before the app or sensitive screens can be opened. - **Confirming sensitive actions**: Ask the user to re-authenticate before critical actions such as payments or deleting data. - **Protecting stored credentials**: Combine biometric authentication with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) or [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugin to guard tokens and passwords. - **Device credential fallback**: Let users fall back to their device PIN or password when biometric authentication is not available or fails. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.5.x | >=8.x.x | Active support | ## Guides - [Announcing the Capacitor Biometrics Plugin](https://capawesome.io/blog/announcing-the-capacitor-biometrics-plugin/) - [Exploring the Capacitor Biometrics API](https://capawesome.io/blog/exploring-the-capacitor-biometrics-api/) - [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/) ## Videos - [How to use Biometrics in a Capacitor Mobile App](https://youtu.be/ixUvTX6n7x8?si=27_X3KiLGAkI9-vJ) ## Installation This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: ``` npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken ``` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-biometrics` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome-team/capacitor-biometrics npx cap sync ``` ### Android #### Proguard If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: ``` -keep class io.capawesome.capacitorjs.plugins.** { *; } ``` #### Variables If needed, you can define the following project variable in your app’s `variables.gradle` file to change the default version of the dependency: - `$androidxBiometricVersion` version of `androidx.biometric:biometric` (default: `1.1.0`) This can be useful if you encounter dependency conflicts with other plugins in your project. ### iOS #### Privacy Descriptions Add the `NSFaceIDUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the biometric authentication: ```xml NSFaceIDUsageDescription This app uses Face ID for authentication. ``` ## Configuration No configuration required for this plugin. ## Usage The following examples show how to check whether biometric authentication can be used, authenticate and cancel the user, prompt for enrollment, and query the device's biometric capabilities. ### Check if biometric authentication can be used Before showing the authentication prompt, check whether biometrics is available on the device and has been configured by the current user. Only available on Android and iOS: ```typescript import { Biometrics } from '@capawesome-team/capacitor-biometrics'; const isAvailable = async () => { const { isAvailable } = await Biometrics.isAvailable(); return isAvailable; }; const isEnrolled = async () => { const { isEnrolled } = await Biometrics.isEnrolled(); return isEnrolled; }; ``` ### Authenticate the user Show a prompt asking the user to authenticate with their biometrics, with a customizable title, subtitle, and button texts. If the authentication succeeds, the promise resolves; if the user cancels or an error occurs, the promise rejects with a detailed error code. Only available on Android and iOS: ```typescript import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics'; const authenticate = async () => { // If the user successfully authenticates, the promise resolves. // If the user cancels the authentication or if an error occurs, the promise rejects. try { await Biometrics.authenticate({ title: 'Authentication Required', subtitle: 'Please authenticate to continue', cancelButtonText: 'Cancel', iosFallbackButtonText: 'Use Passcode', allowDeviceCredential: true, }); } catch (error) { if (error.code === ErrorCode.USER_CANCELED) { console.log('User canceled the authentication.'); } else if (error.code === ErrorCode.NOT_ENROLLED) { console.log('No biometric authentication enrolled.'); } else if (error.code === ErrorCode.NOT_AVAILABLE) { console.log('Biometric authentication not available.'); } else { console.log('Another error occurred:', error); } } }; ``` ### Cancel an ongoing authentication Cancel the ongoing authentication session and dismiss the prompt. Only available on Android (SDK 29+) and iOS: ```typescript import { Biometrics } from '@capawesome-team/capacitor-biometrics'; const cancelAuthentication = async () => { await Biometrics.cancelAuthentication(); }; ``` ### Prompt the user to enroll their biometrics If the user has not yet set up biometric authentication, you can prompt them to enroll. Only available on Android: ```typescript import { Biometrics } from '@capawesome-team/capacitor-biometrics'; const enroll = async () => { await Biometrics.enroll(); }; ``` ### Check the device's biometric capabilities Query the supported biometric strength level (only available on Android) and check whether the user has set up a device credential such as a PIN or password: ```typescript import { Biometrics } from '@capawesome-team/capacitor-biometrics'; const getBiometricStrengthLevel = async () => { const { strengthLevel } = await Biometrics.getBiometricStrengthLevel(); return strengthLevel; }; const hasDeviceCredential = async () => { const { hasDeviceCredential } = await Biometrics.hasDeviceCredential(); return hasDeviceCredential; }; ``` ## API * [`authenticate(...)`](#authenticate) * [`cancelAuthentication()`](#cancelauthentication) * [`enroll()`](#enroll) * [`getAuthenticationType()`](#getauthenticationtype) * [`getBiometricStrengthLevel()`](#getbiometricstrengthlevel) * [`getBiometricType()`](#getbiometrictype) * [`getBiometricTypes()`](#getbiometrictypes) * [`hasDeviceCredential()`](#hasdevicecredential) * [`isAllowed()`](#isallowed) * [`isAvailable()`](#isavailable) * [`isEnrolled()`](#isenrolled) * [`isLockedOut()`](#islockedout) * [Interfaces](#interfaces) * [Enums](#enums) ### authenticate(...) ```typescript authenticate(options?: AuthenticateOptions | undefined) => Promise ``` Authenticates the user locally using the device's biometric authentication. This method will show a prompt to the user asking them to authenticate using their biometrics (e.g., fingerprint, face recognition). If the user successfully authenticates, the promise resolves. If the user cancels the authentication or if an error occurs, the promise rejects. It is recommended to check if biometrics is available and enrolled using the `isAvailable()` and `isEnrolled()` methods before calling this method. On **iOS**, the first time the user is prompted to authenticate, they will be asked for permission to use biometrics. If the user denies permission, the promise will reject with an error. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | AuthenticateOptions | **Since:** 0.1.0 -------------------- ### cancelAuthentication() ```typescript cancelAuthentication() => Promise ``` Cancel the ongoing authentication session and dismisses the prompt. This method is only available on Android (SDK 29+) and iOS. **Since:** 7.0.0 -------------------- ### enroll() ```typescript enroll() => Promise ``` Prompt the user to enroll their biometrics. This method is only available on Android. **Since:** 7.0.0 -------------------- ### getAuthenticationType() ```typescript getAuthenticationType() => Promise ``` Check whether the user authenticated using a device credential or a biometric credential. Only available on Android. **Returns:** Promise<GetAuthenticationTypeResult> **Since:** 0.2.0 -------------------- ### getBiometricStrengthLevel() ```typescript getBiometricStrengthLevel() => Promise ``` Returns the biometric strength level of the device. Only available on Android. **Returns:** Promise<GetBiometricStrengthLevelResult> **Since:** 0.1.0 -------------------- ### getBiometricType() ```typescript getBiometricType() => Promise ``` Returns the type of biometric authentication available on the device. If multiple biometric types are available, returns the highest priority type based on the following order: Face > Iris > Fingerprint. Only available on Android and iOS. **Returns:** Promise<GetBiometricTypeResult> **Since:** 0.5.1 -------------------- ### getBiometricTypes() ```typescript getBiometricTypes() => Promise ``` Returns all biometric authentication types available on the device. On **iOS**, this returns at most a single-element array because the platform exposes only one biometric type per device. If no biometric authentication is available, an empty array is returned. Only available on Android and iOS. **Returns:** Promise<GetBiometricTypesResult> **Since:** 0.5.4 -------------------- ### hasDeviceCredential() ```typescript hasDeviceCredential() => Promise ``` Check whether or not the device's credential (e.g., PIN, password) has been set up by the current user of the device. Only available on Android and iOS. **Returns:** Promise<HasDeviceCredentialResult> **Since:** 0.1.0 -------------------- ### isAllowed() ```typescript isAllowed() => Promise ``` Check whether the user has granted permission to use biometric authentication. On **Android**, biometrics have no OS-level permission gate, so this always resolves to `true`. On **iOS**, this returns `false` only after the user has explicitly denied the Face ID permission prompt. Before the first `authenticate()` call it returns `true`, since iOS provides no API to distinguish the pre-prompt state from a granted state. Only available on Android and iOS. **Returns:** Promise<IsAllowedResult> **Since:** 0.5.4 -------------------- ### isAvailable() ```typescript isAvailable() => Promise ``` Check whether or not biometrics is available on the device. Only available on Android and iOS. **Returns:** Promise<IsAvailableResult> **Since:** 0.1.0 -------------------- ### isEnrolled() ```typescript isEnrolled() => Promise ``` Check whether or not biometrics is available on the device and has been configured by the current user of the device. Only available on Android and iOS. **Returns:** Promise<IsEnrolledResult> **Since:** 0.1.0 -------------------- ### isLockedOut() ```typescript isLockedOut() => Promise ``` Check whether biometric authentication is currently locked out due to too many failed attempts. On **Android**, the platform exposes no queryable lockout status. This returns `true` only if the most recent `authenticate()` call in the current process failed with a lockout error; the state is cleared on the next successful authentication or process restart. Only available on Android and iOS. **Returns:** Promise<IsLockedOutResult> **Since:** 0.5.4 -------------------- ### Interfaces #### AuthenticateOptions | Prop | Type | Description | Default | Since | | ------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----- | | **`allowDeviceCredential`** | boolean | Whether or not to allow the user to authenticate using their device's credential (e.g., PIN, password) if biometric authentication is not available or fails. You can check if the device's credential is set up using the `hasDeviceCredential()` method. | false | 0.1.0 | | **`androidBiometricStrength`** | BiometricStrength | The Android biometric strength to use for authentication. You can check the supported biometric strength level of the device using the `getBiometricStrengthLevel()` method. **Note**: On Android API Level 28 and 29, this will always be set to `AndroidBiometricStrength.WEAK` regardless of the value passed in if `allowDeviceCredential` is set to `true`. This is a known limitation. Only available on Android. | AndroidBiometricStrength.WEAK | 0.1.0 | | **`cancelButtonText`** | string | The negative button text of the authentication prompt. | | 0.1.0 | | **`iosFallbackButtonText`** | string | The fallback button text of the authentication prompt. Only available on iOS. | | 0.1.0 | | **`subtitle`** | string | The subtitle of the authentication prompt. | | 0.1.0 | | **`title`** | string | The title of the authentication prompt. | | 0.1.0 | #### GetAuthenticationTypeResult | Prop | Type | Description | Since | | ------------------------ | ----------------------------------------------------------------- | -------------------------------------------- | ----- | | **`authenticationType`** | AuthenticationType | The type of authentication used by the user. | 0.2.0 | #### GetBiometricStrengthLevelResult | Prop | Type | Description | Since | | ------------------- | --------------------------------------------------------------- | ----------------------------------------------------- | ----- | | **`strengthLevel`** | BiometricStrength | The supported biometric strength level of the device. | 0.1.0 | #### GetBiometricTypeResult | Prop | Type | Description | Since | | ------------------- | ------------------------------------------------------- | ------------------------------------------------------------- | ----- | | **`biometricType`** | BiometricType | The type of biometric authentication available on the device. | 0.5.1 | #### GetBiometricTypesResult | Prop | Type | Description | Since | | ----------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ----- | | **`types`** | BiometricType[] | The biometric authentication types available on the device. Empty if no biometric authentication is available. | 0.5.4 | #### HasDeviceCredentialResult | Prop | Type | Description | Since | | ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ----- | | **`hasDeviceCredential`** | boolean | Whether or not the device's credential (e.g., PIN, password) has been set up by the current user of the device. | 0.1.0 | #### IsAllowedResult | Prop | Type | Description | Since | | --------------- | -------------------- | ------------------------------------------------------------------------------- | ----- | | **`isAllowed`** | boolean | Whether or not the user has granted permission to use biometric authentication. | 0.5.4 | #### IsAvailableResult | Prop | Type | Description | Since | | ----------------- | -------------------- | ------------------------------------------------------------------- | ----- | | **`isAvailable`** | boolean | Whether or not biometric authentication is available on the device. | 0.1.0 | #### IsEnrolledResult | Prop | Type | Description | Since | | ---------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ----- | | **`isEnrolled`** | boolean | Whether or not biometrics is supported by the device and has been configured by the current user of the device. | 0.1.0 | #### IsLockedOutResult | Prop | Type | Description | Since | | ----------------- | -------------------- | ------------------------------------------------------------------------------------------------ | ----- | | **`isLockedOut`** | boolean | Whether or not biometric authentication is currently locked out due to too many failed attempts. | 0.5.4 | ### Enums #### BiometricStrength | Members | Value | Since | | ------------ | --------------------- | ----- | | **`Strong`** | 'STRONG' | 0.1.0 | | **`Weak`** | 'WEAK' | 0.1.0 | #### AuthenticationType | Members | Value | Description | Since | | ---------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`Biometric`** | 'BIOMETRIC' | The user authenticated using a biometric credential. | 0.2.0 | | **`DeviceCredential`** | 'DEVICE_CREDENTIAL' | The user authenticated using a device credential (e.g., PIN, password). | 0.2.0 | | **`Unknown`** | 'UNKNOWN' | The user authenticated via an unknown method. This value may be returned on older Android versions due to partial incompatibility with a newer API. | 0.2.0 | #### BiometricType | Members | Value | Description | Since | | ----------------- | -------------------------- | --------------------------------------------------------------------- | ----- | | **`Face`** | 'FACE' | Face authentication (Face ID on iOS, face recognition on Android). | 0.5.1 | | **`Fingerprint`** | 'FINGERPRINT' | Fingerprint authentication (Touch ID on iOS, fingerprint on Android). | 0.5.1 | | **`Iris`** | 'IRIS' | Iris authentication. Only available on Android. | 0.5.1 | | **`None`** | 'NONE' | No biometric authentication available on the device. | 0.5.1 | ## FAQ ### Which biometric authentication methods are supported? The plugin supports fingerprint, face, and iris recognition, where iris recognition is only available on Android. You can query the available methods on the device using the `getBiometricType()` and `getBiometricTypes()` methods. ### Can users authenticate with their device PIN or password instead? Yes, set the `allowDeviceCredential` option of the `authenticate(...)` method to `true` to allow the user to authenticate with their device credential (e.g. PIN or password) if biometric authentication is not available or fails. You can check whether a device credential has been set up using the `hasDeviceCredential()` method. ### How do I check if biometric authentication is available before showing the prompt? It is recommended to call the `isAvailable()` and `isEnrolled()` methods before calling `authenticate(...)`. This way you can check whether biometrics is available on the device and has been configured by the current user. See the [usage example](#check-if-biometric-authentication-can-be-used) above. ### How do I handle a failed or canceled authentication? If the user cancels the authentication or an error occurs, the promise returned by `authenticate(...)` rejects with a detailed error code such as `USER_CANCELED`, `NOT_ENROLLED`, or `NOT_AVAILABLE`. See the [usage example](#authenticate-the-user) above for how to handle these error codes. ### What configuration is required on iOS? You need to add the `NSFaceIDUsageDescription` key to your `Info.plist` file as described in the [Installation](#installation) section. The first time the user is prompted to authenticate, iOS will ask for permission to use biometrics; if the user denies it, the promise rejects with an error. ### How can I securely store credentials behind biometric authentication? The plugin is compatible with the [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) and [Vault](https://capawesome.io/docs/sdks/capacitor/vault/) plugins, which can store sensitive key/value pairs. Check out the guide [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/) for a complete walkthrough. ## Related Plugins - [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers. - [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard. - [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information. - [Vault](https://capawesome.io/docs/sdks/capacitor/vault/): Securely store key/value pairs in lockable, biometric-protected vaults. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/CHANGELOG.md). ## Breaking Changes See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/BREAKING.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/LICENSE).