--- 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/plugins/biometrics.png --- [ Skip to content](#capawesome-teamcapacitor-biometrics) [ πŸŽ‰ Introducing **Capawesome Platform** β€” one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) * [ iOS ](#ios) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Bluetooth Low Energy ](/docs/plugins/bluetooth-low-energy/) * [ Cloudinary ](/docs/plugins/cloudinary/) * [ Contacts ](/docs/plugins/contacts/) * [ Datetime Picker ](/docs/plugins/datetime-picker/) * [ File Compressor ](/docs/plugins/file-compressor/) * [ File Opener ](/docs/plugins/file-opener/) * [ File Picker ](/docs/plugins/file-picker/) * [ Firebase ](/docs/plugins/firebase/) * [ Formbricks ](/docs/plugins/formbricks/) * [ Geocoder ](/docs/plugins/geocoder/) * [ Google Sign-In ](/docs/plugins/google-sign-in/) * [ Grafana Faro ](/docs/plugins/grafana-faro/) * [ libSQL ](/docs/plugins/libsql/) * [ Live Update ](/docs/plugins/live-update/) * [ Managed Configurations ](/docs/plugins/managed-configurations/) * [ Media Session ](/docs/plugins/media-session/) * [ ML Kit ](/docs/plugins/mlkit/) * [ Navigation Bar ](/docs/plugins/navigation-bar/) * [ NFC ](/docs/plugins/nfc/) * [ OAuth ](/docs/plugins/oauth/) * [ Pedometer ](/docs/plugins/pedometer/) * [ Photo Editor ](/docs/plugins/photo-editor/) * [ PostHog ](/docs/plugins/posthog/) * [ Printer ](/docs/plugins/printer/) * [ Purchases ](/docs/plugins/purchases/) * [ RealtimeKit ](/docs/plugins/realtimekit/) * [ Screen Orientation ](/docs/plugins/screen-orientation/) * [ Screenshot ](/docs/plugins/screenshot/) * [ Secure Preferences ](/docs/plugins/secure-preferences/) * [ Speech Recognition ](/docs/plugins/speech-recognition/) * [ Speech Synthesis ](/docs/plugins/speech-synthesis/) * [ Share Target ](/docs/plugins/share-target/) * [ Square Mobile Payments ](/docs/plugins/square-mobile-payments/) * [ SQLite ](/docs/plugins/sqlite/) * [ Superwall ](/docs/plugins/superwall/) * [ Torch ](/docs/plugins/torch/) * [ Wifi ](/docs/plugins/wifi/) * [ Zip ](/docs/plugins/zip/) * [ Cloud ](/docs/cloud/) * [ Live Updates ](/docs/cloud/live-updates/) * Advanced * Integrations * [ Native Builds ](/docs/cloud/native-builds/) * [ Configuration ](/docs/cloud/native-builds/configuration/) * [ Environments ](/docs/cloud/native-builds/environments/) * Guides * [ Sample Projects ](/docs/cloud/native-builds/sample-projects/) * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ Automations ](/docs/cloud/automations/) * [ Assist ](/docs/cloud/assist/) * Account * Organizations * [ Organization and User Management ](/docs/cloud/organizations/memberships/) * [ Single Sign-On (SSO) ](/docs/cloud/organizations/sso/) * [ Teams ](/docs/cloud/organizations/teams/) * [ Two-Factor Authentication ](/docs/cloud/organizations/two-factor-authentication/) * [ Integrations ](/docs/cloud/integrations/) * [ License Keys ](/docs/cloud/license-keys/) * [ Webhooks ](/docs/cloud/webhooks/) * [ Pricing ](https://capawesome.io/pricing/) * [ FAQ ](/docs/cloud/faq/) * [ Support ](/docs/cloud/support/) * [ Contributing ](/docs/contributing/) * [ LLMs ](/docs/llms/) * [ Insiders ](/docs/insiders/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/insiders/support/) * [ FAQ ](/docs/insiders/faq/) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # @capawesome-team/capacitor-biometrics[ΒΆ](#capawesome-teamcapacitor-biometrics "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") We are proud to offer one of the most complete and feature-rich Capacitor plugins for biometric authentication. 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/plugins/secure-preferences/) plugin. * πŸ“¦ **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! ## 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/). ## 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. ` ## Usage[ΒΆ](#usage "Permanent link") `[](#%5F%5Fcodelineno-6-1)import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const authenticate = async () => { [](#%5F%5Fcodelineno-6-4) // If the user successfully authenticates, the promise resolves. [](#%5F%5Fcodelineno-6-5) // If the user cancels the authentication or if an error occurs, the promise rejects. [](#%5F%5Fcodelineno-6-6) try { [](#%5F%5Fcodelineno-6-7) await Biometrics.authenticate({ [](#%5F%5Fcodelineno-6-8) title: 'Authentication Required', [](#%5F%5Fcodelineno-6-9) subtitle: 'Please authenticate to continue', [](#%5F%5Fcodelineno-6-10) cancelButtonText: 'Cancel', [](#%5F%5Fcodelineno-6-11) iosFallbackButtonText: 'Use Passcode', [](#%5F%5Fcodelineno-6-12) allowDeviceCredential: true, [](#%5F%5Fcodelineno-6-13) }); [](#%5F%5Fcodelineno-6-14) } catch (error) { [](#%5F%5Fcodelineno-6-15) if (error.code === ErrorCode.USER_CANCELED) { [](#%5F%5Fcodelineno-6-16) console.log('User canceled the authentication.'); [](#%5F%5Fcodelineno-6-17) } else if (error.code === ErrorCode.NOT_ENROLLED) { [](#%5F%5Fcodelineno-6-18) console.log('No biometric authentication enrolled.'); [](#%5F%5Fcodelineno-6-19) } else if (error.code === ErrorCode.NOT_AVAILABLE) { [](#%5F%5Fcodelineno-6-20) console.log('Biometric authentication not available.'); [](#%5F%5Fcodelineno-6-21) } else { [](#%5F%5Fcodelineno-6-22) console.log('Another error occurred:', error); [](#%5F%5Fcodelineno-6-23) } [](#%5F%5Fcodelineno-6-24) } [](#%5F%5Fcodelineno-6-25)}; [](#%5F%5Fcodelineno-6-26) [](#%5F%5Fcodelineno-6-27)const cancelAuthentication = async () => { [](#%5F%5Fcodelineno-6-28) await Biometrics.cancelAuthentication(); [](#%5F%5Fcodelineno-6-29)}; [](#%5F%5Fcodelineno-6-30) [](#%5F%5Fcodelineno-6-31)const enroll = async () => { [](#%5F%5Fcodelineno-6-32) await Biometrics.enroll(); [](#%5F%5Fcodelineno-6-33)}; [](#%5F%5Fcodelineno-6-34) [](#%5F%5Fcodelineno-6-35) [](#%5F%5Fcodelineno-6-36)const getBiometricStrengthLevel = async () => { [](#%5F%5Fcodelineno-6-37) const { strengthLevel } = await Biometrics.getBiometricStrengthLevel(); [](#%5F%5Fcodelineno-6-38) return strengthLevel; [](#%5F%5Fcodelineno-6-39)}; [](#%5F%5Fcodelineno-6-40) [](#%5F%5Fcodelineno-6-41)const hasDeviceCredential = async () => { [](#%5F%5Fcodelineno-6-42) const { hasDeviceCredential } = await Biometrics.hasDeviceCredential(); [](#%5F%5Fcodelineno-6-43) return hasDeviceCredential; [](#%5F%5Fcodelineno-6-44)}; [](#%5F%5Fcodelineno-6-45) [](#%5F%5Fcodelineno-6-46)const isAvailable = async () => { [](#%5F%5Fcodelineno-6-47) const { isAvailable } = await Biometrics.isAvailable(); [](#%5F%5Fcodelineno-6-48) return isAvailable; [](#%5F%5Fcodelineno-6-49)}; [](#%5F%5Fcodelineno-6-50) [](#%5F%5Fcodelineno-6-51)const isEnrolled = async () => { [](#%5F%5Fcodelineno-6-52) const { isEnrolled } = await Biometrics.isEnrolled(); [](#%5F%5Fcodelineno-6-53) return isEnrolled; [](#%5F%5Fcodelineno-6-54)}; ` ## API[ΒΆ](#api "Permanent link") * [authenticate(...)](#authenticate) * [cancelAuthentication()](#cancelauthentication) * [enroll()](#enroll) * [getAuthenticationType()](#getauthenticationtype) * [getBiometricStrengthLevel()](#getbiometricstrengthlevel) * [getBiometricType()](#getbiometrictype) * [hasDeviceCredential()](#hasdevicecredential) * [isAvailable()](#isavailable) * [isEnrolled()](#isenrolled) * [Interfaces](#interfaces) * [Enums](#enums) ### authenticate(...)[ΒΆ](#authenticate "Permanent link") `[](#%5F%5Fcodelineno-7-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-8-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-9-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-10-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-11-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-12-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 --- ### hasDeviceCredential()[ΒΆ](#hasdevicecredential "Permanent link") `[](#%5F%5Fcodelineno-13-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 --- ### isAvailable()[ΒΆ](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-14-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-15-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 --- ### 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 | #### 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 | #### 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 | ### 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 | ## 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). May 17, 2026 Back to top