--- description: Capacitor Biometrics plugin to request biometric authentication, such as Face ID, fingerprint, and device credential auth for Android and iOS. title: Capacitor Biometrics Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/biometrics.png --- [Skip to content ](#capacitor-biometrics-plugin) [πŸ” Introducing the **Capacitor Vault** plugin β€” store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/) * [ SDKs ](/docs/sdks/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Bluetooth Low Energy ](/docs/sdks/capacitor/bluetooth-low-energy/) * [ Clipboard ](/docs/sdks/capacitor/clipboard/) * [ Cloudinary ](/docs/sdks/capacitor/cloudinary/) * [ Compass ](/docs/sdks/capacitor/compass/) * [ Contacts ](/docs/sdks/capacitor/contacts/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor Biometrics Plugin[ΒΆ](#capacitor-biometrics-plugin "Permanent link") Capacitor plugin to request biometric authentication, such as using face recognition or fingerprint recognition. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") 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[ΒΆ](#use-cases "Permanent link") 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[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.5.x | \>=8.x.x | Active support | ## Guides[ΒΆ](#guides "Permanent link") * [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[ΒΆ](#videos "Permanent link") * [How to use Biometrics in a Capacitor Mobile App](https://youtu.be/ixUvTX6n7x8?si=27%5FX3KiLGAkI9-vJ) ## Installation[ΒΆ](#installation "Permanent link") 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: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)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: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)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: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-biometrics [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Proguard[ΒΆ](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-4-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` #### Variables[ΒΆ](#variables "Permanent link") 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[ΒΆ](#ios "Permanent link") #### Privacy Descriptions[ΒΆ](#privacy-descriptions "Permanent link") 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: `[](#%5F%5Fcodelineno-5-1)NSFaceIDUsageDescription [](#%5F%5Fcodelineno-5-2)This app uses Face ID for authentication. ` ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") 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[ΒΆ](#check-if-biometric-authentication-can-be-used "Permanent link") 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: `[](#%5F%5Fcodelineno-6-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const isAvailable = async () => { [](#%5F%5Fcodelineno-6-4) const { isAvailable } = await Biometrics.isAvailable(); [](#%5F%5Fcodelineno-6-5) return isAvailable; [](#%5F%5Fcodelineno-6-6)}; [](#%5F%5Fcodelineno-6-7) [](#%5F%5Fcodelineno-6-8)const isEnrolled = async () => { [](#%5F%5Fcodelineno-6-9) const { isEnrolled } = await Biometrics.isEnrolled(); [](#%5F%5Fcodelineno-6-10) return isEnrolled; [](#%5F%5Fcodelineno-6-11)}; ` ### Authenticate the user[ΒΆ](#authenticate-the-user "Permanent link") 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: `[](#%5F%5Fcodelineno-7-1)import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const authenticate = async () => { [](#%5F%5Fcodelineno-7-4) // If the user successfully authenticates, the promise resolves. [](#%5F%5Fcodelineno-7-5) // If the user cancels the authentication or if an error occurs, the promise rejects. [](#%5F%5Fcodelineno-7-6) try { [](#%5F%5Fcodelineno-7-7) await Biometrics.authenticate({ [](#%5F%5Fcodelineno-7-8) title: 'Authentication Required', [](#%5F%5Fcodelineno-7-9) subtitle: 'Please authenticate to continue', [](#%5F%5Fcodelineno-7-10) cancelButtonText: 'Cancel', [](#%5F%5Fcodelineno-7-11) iosFallbackButtonText: 'Use Passcode', [](#%5F%5Fcodelineno-7-12) allowDeviceCredential: true, [](#%5F%5Fcodelineno-7-13) }); [](#%5F%5Fcodelineno-7-14) } catch (error) { [](#%5F%5Fcodelineno-7-15) if (error.code === ErrorCode.USER_CANCELED) { [](#%5F%5Fcodelineno-7-16) console.log('User canceled the authentication.'); [](#%5F%5Fcodelineno-7-17) } else if (error.code === ErrorCode.NOT_ENROLLED) { [](#%5F%5Fcodelineno-7-18) console.log('No biometric authentication enrolled.'); [](#%5F%5Fcodelineno-7-19) } else if (error.code === ErrorCode.NOT_AVAILABLE) { [](#%5F%5Fcodelineno-7-20) console.log('Biometric authentication not available.'); [](#%5F%5Fcodelineno-7-21) } else { [](#%5F%5Fcodelineno-7-22) console.log('Another error occurred:', error); [](#%5F%5Fcodelineno-7-23) } [](#%5F%5Fcodelineno-7-24) } [](#%5F%5Fcodelineno-7-25)}; ` ### Cancel an ongoing authentication[ΒΆ](#cancel-an-ongoing-authentication "Permanent link") Cancel the ongoing authentication session and dismiss the prompt. Only available on Android (SDK 29+) and iOS: `[](#%5F%5Fcodelineno-8-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const cancelAuthentication = async () => { [](#%5F%5Fcodelineno-8-4) await Biometrics.cancelAuthentication(); [](#%5F%5Fcodelineno-8-5)}; ` ### Prompt the user to enroll their biometrics[ΒΆ](#prompt-the-user-to-enroll-their-biometrics "Permanent link") If the user has not yet set up biometric authentication, you can prompt them to enroll. Only available on Android: `[](#%5F%5Fcodelineno-9-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const enroll = async () => { [](#%5F%5Fcodelineno-9-4) await Biometrics.enroll(); [](#%5F%5Fcodelineno-9-5)}; ` ### Check the device's biometric capabilities[ΒΆ](#check-the-devices-biometric-capabilities "Permanent link") 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: `[](#%5F%5Fcodelineno-10-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const getBiometricStrengthLevel = async () => { [](#%5F%5Fcodelineno-10-4) const { strengthLevel } = await Biometrics.getBiometricStrengthLevel(); [](#%5F%5Fcodelineno-10-5) return strengthLevel; [](#%5F%5Fcodelineno-10-6)}; [](#%5F%5Fcodelineno-10-7) [](#%5F%5Fcodelineno-10-8)const hasDeviceCredential = async () => { [](#%5F%5Fcodelineno-10-9) const { hasDeviceCredential } = await Biometrics.hasDeviceCredential(); [](#%5F%5Fcodelineno-10-10) return hasDeviceCredential; [](#%5F%5Fcodelineno-10-11)}; ` ## API[ΒΆ](#api "Permanent link") * [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(...)[ΒΆ](#authenticate "Permanent link") `[](#%5F%5Fcodelineno-11-1)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](#authenticateoptions) | **Since:** 0.1.0 --- ### cancelAuthentication()[ΒΆ](#cancelauthentication "Permanent link") `[](#%5F%5Fcodelineno-12-1)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()[ΒΆ](#enroll "Permanent link") `[](#%5F%5Fcodelineno-13-1)enroll() => Promise ` Prompt the user to enroll their biometrics. This method is only available on Android. **Since:** 7.0.0 --- ### getAuthenticationType()[ΒΆ](#getauthenticationtype "Permanent link") `[](#%5F%5Fcodelineno-14-1)getAuthenticationType() => Promise ` Check whether the user authenticated using a device credential or a biometric credential. Only available on Android. **Returns:** `Promise<[GetAuthenticationTypeResult](#getauthenticationtyperesult)>` **Since:** 0.2.0 --- ### getBiometricStrengthLevel()[ΒΆ](#getbiometricstrengthlevel "Permanent link") `[](#%5F%5Fcodelineno-15-1)getBiometricStrengthLevel() => Promise ` Returns the biometric strength level of the device. Only available on Android. **Returns:** `Promise<[GetBiometricStrengthLevelResult](#getbiometricstrengthlevelresult)>` **Since:** 0.1.0 --- ### getBiometricType()[ΒΆ](#getbiometrictype "Permanent link") `[](#%5F%5Fcodelineno-16-1)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](#getbiometrictyperesult)>` **Since:** 0.5.1 --- ### getBiometricTypes()[ΒΆ](#getbiometrictypes "Permanent link") `[](#%5F%5Fcodelineno-17-1)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](#getbiometrictypesresult)>` **Since:** 0.5.4 --- ### hasDeviceCredential()[ΒΆ](#hasdevicecredential "Permanent link") `[](#%5F%5Fcodelineno-18-1)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](#hasdevicecredentialresult)>` **Since:** 0.1.0 --- ### isAllowed()[ΒΆ](#isallowed "Permanent link") `[](#%5F%5Fcodelineno-19-1)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](#isallowedresult)>` **Since:** 0.5.4 --- ### isAvailable()[ΒΆ](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-20-1)isAvailable() => Promise ` Check whether or not biometrics is available on the device. Only available on Android and iOS. **Returns:** `Promise<[IsAvailableResult](#isavailableresult)>` **Since:** 0.1.0 --- ### isEnrolled()[ΒΆ](#isenrolled "Permanent link") `[](#%5F%5Fcodelineno-21-1)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](#isenrolledresult)>` **Since:** 0.1.0 --- ### isLockedOut()[ΒΆ](#islockedout "Permanent link") `[](#%5F%5Fcodelineno-22-1)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](#islockedoutresult)>` **Since:** 0.5.4 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### AuthenticateOptions[ΒΆ](#authenticateoptions "Permanent link") | 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](#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[ΒΆ](#getauthenticationtyperesult "Permanent link") | Prop | Type | Description | Since | | ---------------------- | ----------------------------------------- | -------------------------------------------- | ----- | | **authenticationType** | [AuthenticationType](#authenticationtype) | The type of authentication used by the user. | 0.2.0 | #### GetBiometricStrengthLevelResult[ΒΆ](#getbiometricstrengthlevelresult "Permanent link") | Prop | Type | Description | Since | | ----------------- | --------------------------------------- | ----------------------------------------------------- | ----- | | **strengthLevel** | [BiometricStrength](#biometricstrength) | The supported biometric strength level of the device. | 0.1.0 | #### GetBiometricTypeResult[ΒΆ](#getbiometrictyperesult "Permanent link") | Prop | Type | Description | Since | | ----------------- | ------------------------------- | ------------------------------------------------------------- | ----- | | **biometricType** | [BiometricType](#biometrictype) | The type of biometric authentication available on the device. | 0.5.1 | #### GetBiometricTypesResult[ΒΆ](#getbiometrictypesresult "Permanent link") | 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[ΒΆ](#hasdevicecredentialresult "Permanent link") | 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[ΒΆ](#isallowedresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ------- | ------------------------------------------------------------------------------- | ----- | | **isAllowed** | boolean | Whether or not the user has granted permission to use biometric authentication. | 0.5.4 | #### IsAvailableResult[ΒΆ](#isavailableresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | ------------------------------------------------------------------- | ----- | | **isAvailable** | boolean | Whether or not biometric authentication is available on the device. | 0.1.0 | #### IsEnrolledResult[ΒΆ](#isenrolledresult "Permanent link") | 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[ΒΆ](#islockedoutresult "Permanent link") | 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[ΒΆ](#enums "Permanent link") #### BiometricStrength[ΒΆ](#biometricstrength "Permanent link") | Members | Value | Since | | ---------- | -------- | ----- | | **Strong** | 'STRONG' | 0.1.0 | | **Weak** | 'WEAK' | 0.1.0 | #### AuthenticationType[ΒΆ](#authenticationtype "Permanent link") | 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[ΒΆ](#biometrictype "Permanent link") | 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[ΒΆ](#faq "Permanent link") ### Which biometric authentication methods are supported?[ΒΆ](#which-biometric-authentication-methods-are-supported "Permanent link") 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?[ΒΆ](#can-users-authenticate-with-their-device-pin-or-password-instead "Permanent link") 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?[ΒΆ](#how-do-i-check-if-biometric-authentication-is-available-before-showing-the-prompt "Permanent link") 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?[ΒΆ](#how-do-i-handle-a-failed-or-canceled-authentication "Permanent link") 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?[ΒΆ](#what-configuration-is-required-on-ios "Permanent link") 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?[ΒΆ](#how-can-i-securely-store-credentials-behind-biometric-authentication "Permanent link") 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[ΒΆ](#related-plugins "Permanent link") * [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. * [Passkeys](https://capawesome.io/docs/sdks/capacitor/passkeys/): Create and authenticate with passkeys based on the WebAuthn standard. * [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers. ## Newsletter[ΒΆ](#newsletter "Permanent link") 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[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/biometrics/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/biometrics/#article", "headline": "Capacitor Biometrics Plugin for Android & iOS", "name": "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.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/biometrics/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/biometrics/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/biometrics/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/biometrics/#software", "name": "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.", "url": "https://capawesome.io/docs/sdks/capacitor/biometrics/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Which biometric authentication methods are supported?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Can users authenticate with their device PIN or password instead?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How do I check if biometric authentication is available before showing the prompt?", "acceptedAnswer": {"@type": "Answer", "text": "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 above."}}, {"@type": "Question", "name": "How do I handle a failed or canceled authentication?", "acceptedAnswer": {"@type": "Answer", "text": "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 above for how to handle these error codes."}}, {"@type": "Question", "name": "What configuration is required on iOS?", "acceptedAnswer": {"@type": "Answer", "text": "You need to add the NSFaceIDUsageDescription key to your Info.plist file as described in the 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."}}, {"@type": "Question", "name": "How can I securely store credentials behind biometric authentication?", "acceptedAnswer": {"@type": "Answer", "text": "The plugin is compatible with the Secure Preferences and Vault plugins, which can store sensitive key/value pairs. Check out the guide How to Securely Store Credentials with Capacitor for a complete walkthrough."}}], "url": "https://capawesome.io/docs/sdks/capacitor/biometrics/"} ```