---
description: Practical guide to the Capacitor Biometrics plugin: Face ID, Touch ID, fingerprint, and passcode auth in Ionic and Capacitor apps.
title: Exploring the Capacitor Biometrics API - Capawesome
image: https://capawesome.io/docs/assets/images/social/blog/exploring-the-capacitor-biometrics-api.png
---

[ Skip to content](#exploring-the-capacitor-biometrics-api) 

[ 🎉 Introducing **Capawesome Platform** — one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) 

* [  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

* [  Best Practices ](#best-practices)
* [  Conclusion ](#conclusion)

* Related links

# Exploring the Capacitor Biometrics API[¶](#exploring-the-capacitor-biometrics-api "Permanent link")

Modern mobile applications increasingly rely on biometric authentication to provide secure and convenient user experiences. With the [Capacitor Biometrics](/docs/plugins/biometrics/) plugin from Capawesome, developers can integrate powerful biometric authentication capabilities into their Ionic and Capacitor applications, enabling fingerprint, face, and iris recognition across Android, iOS, and Web platforms through a unified API that simplifies the complexity of platform-specific biometric implementations.

This guide covers the **Capacitor Biometrics** API with practical examples and best practices. For the full **Capacitor Biometrics plugin documentation**, see the [API Reference](/docs/plugins/biometrics/#api).

## Bonus: Video Tutorial and Demo App[¶](#bonus-video-tutorial-and-demo-app "Permanent link")

We created a **step-by-step video tutorial** that walks through installing the plugin, configuring iOS Face ID permissions, organizing your biometrics logic in a small helper module, triggering authentication from the app UI, and handling success and error states.

* **[Capacitor Biometrics Demo App](https://github.com/capawesome-team/capacitor-biometrics-demo)** — A minimal, framework-agnostic demo (vanilla JavaScript and Capacitor) with a complete biometric authentication flow using Face ID or fingerprint.

The tutorial assumes you already have a Capacitor app; it focuses only on the Biometrics integration. For the full API, see the [plugin documentation](/docs/plugins/biometrics/).

## Installation[¶](#installation "Permanent link")

To install the Capacitor Biometrics plugin, please refer to the [Installation](/docs/plugins/biometrics/#installation) section in the plugin documentation.

## Usage[¶](#usage "Permanent link")

Let's explore the key features of the Capacitor Biometrics API and how to implement them in your Ionic applications.

### Checking Availability[¶](#checking-availability "Permanent link")

Before implementing biometric authentication, it's crucial to verify if biometric features are available on the device. The Capacitor Biometrics API provides the [isAvailable(...)](/docs/plugins/biometrics/#isavailable) method for this purpose:

`[](#%5F%5Fcodelineno-0-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics';
[](#%5F%5Fcodelineno-0-2)
[](#%5F%5Fcodelineno-0-3)const isAvailable = async () => {
[](#%5F%5Fcodelineno-0-4)  const result = await Biometrics.isAvailable();
[](#%5F%5Fcodelineno-0-5)
[](#%5F%5Fcodelineno-0-6)  if (!result.isAvailable) {
[](#%5F%5Fcodelineno-0-7)    alert('Biometric authentication is not available on this device.');
[](#%5F%5Fcodelineno-0-8)    return;
[](#%5F%5Fcodelineno-0-9)  }
[](#%5F%5Fcodelineno-0-10)};
`

Make sure to call this method once before attempting any biometric operations. If no biometric features are available, you can gracefully handle the situation by informing the user or providing alternative authentication methods.

### Checking Enrollment[¶](#checking-enrollment "Permanent link")

Biometric authentication should not only but supported by the device, but also configured by the user. The [isEnrolled(...)](/docs/plugins/biometrics/#isenrolled) method allows you to check if the user has enrolled biometric data on their device:

`[](#%5F%5Fcodelineno-1-1)const isEnrolled = async () => {
[](#%5F%5Fcodelineno-1-2)  const result = await Biometrics.isEnrolled();
[](#%5F%5Fcodelineno-1-3)
[](#%5F%5Fcodelineno-1-4)  if (!result.isEnrolled) {
[](#%5F%5Fcodelineno-1-5)    alert('Please enroll biometric data in your device settings to use this feature.');
[](#%5F%5Fcodelineno-1-6)  }
[](#%5F%5Fcodelineno-1-7)};
`

If the user has not enrolled any biometric data, you can prompt them to do so through their device settings. On Android, you can even use the [enroll(...)](/docs/plugins/biometrics/#enroll) method to guide users through the enrollment process directly from your app:

`[](#%5F%5Fcodelineno-2-1)import { Biometrics } from '@capawesome-team/capacitor-biometrics';
[](#%5F%5Fcodelineno-2-2)
[](#%5F%5Fcodelineno-2-3)const enroll = async () => {
[](#%5F%5Fcodelineno-2-4)  await Biometrics.enroll();
[](#%5F%5Fcodelineno-2-5)};
`

This will open the device's biometric enrollment screen, allowing users to add their biometric data without leaving your application.

### Authenticating with Biometrics[¶](#authenticating-with-biometrics "Permanent link")

The core functionality of the plugin is provided through the [authenticate(...)](/docs/plugins/biometrics/#authenticate) method, which triggers the biometric authentication process:

`[](#%5F%5Fcodelineno-3-1)import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';
[](#%5F%5Fcodelineno-3-2)
[](#%5F%5Fcodelineno-3-3)const authenticate = async () => {
[](#%5F%5Fcodelineno-3-4)  // If the user successfully authenticates, the promise resolves.
[](#%5F%5Fcodelineno-3-5)  // If the user cancels the authentication or if an error occurs, the promise rejects.
[](#%5F%5Fcodelineno-3-6)  try {
[](#%5F%5Fcodelineno-3-7)    await Biometrics.authenticate({
[](#%5F%5Fcodelineno-3-8)      title: 'Authentication Required',
[](#%5F%5Fcodelineno-3-9)      subtitle: 'Please authenticate to continue',
[](#%5F%5Fcodelineno-3-10)      cancelButtonText: 'Cancel',
[](#%5F%5Fcodelineno-3-11)      iosFallbackButtonText: 'Use Passcode',
[](#%5F%5Fcodelineno-3-12)    });
[](#%5F%5Fcodelineno-3-13)  } catch (error) {
[](#%5F%5Fcodelineno-3-14)    if (error.code === ErrorCode.USER_CANCELED) {
[](#%5F%5Fcodelineno-3-15)      console.log('User canceled the authentication.');
[](#%5F%5Fcodelineno-3-16)    } else if (error.code === ErrorCode.NOT_ENROLLED) {
[](#%5F%5Fcodelineno-3-17)      console.log('No biometric authentication enrolled.');
[](#%5F%5Fcodelineno-3-18)    } else if (error.code === ErrorCode.NOT_AVAILABLE) {
[](#%5F%5Fcodelineno-3-19)      console.log('Biometric authentication not available.');
[](#%5F%5Fcodelineno-3-20)    } else {
[](#%5F%5Fcodelineno-3-21)      console.log('Another error occurred:', error);
[](#%5F%5Fcodelineno-3-22)    }
[](#%5F%5Fcodelineno-3-23)  }
[](#%5F%5Fcodelineno-3-24)};
`

The `authenticate(...)` method accepts various configuration options to customize the authentication prompt, including titles, descriptions, and fallback options. 

Make sure to handle the promise rejection properly to manage different error scenarios, such as user cancellation, biometric not enrolled, or biometric not available.

### Authenticating with Device Credentials[¶](#authenticating-with-device-credentials "Permanent link")

In addition to biometric authentication, the Capacitor Biometrics API supports device credentials (PIN, pattern, or password) as a fallback option. You can enable this feature by setting the `allowDeviceCredential` option to `true` in the `authenticate(...)` method:

`[](#%5F%5Fcodelineno-4-1)import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';
[](#%5F%5Fcodelineno-4-2)
[](#%5F%5Fcodelineno-4-3)const authenticate = async () => {
[](#%5F%5Fcodelineno-4-4)  await Biometrics.authenticate({
[](#%5F%5Fcodelineno-4-5)    allowDeviceCredential: true,
[](#%5F%5Fcodelineno-4-6)  });
[](#%5F%5Fcodelineno-4-7)};
`

This allows users to authenticate using their device credentials if biometric recognition fails or is temporarily unavailable. It provides a seamless user experience by ensuring that authentication can still proceed even when biometrics are not an option.

Make sure to check if the device supports device credentials before enabling this option. You can do this using the [hasDeviceCredential(...)](/docs/plugins/biometrics/#hasdevicecredential) method:

`[](#%5F%5Fcodelineno-5-1)const checkDeviceCredential = async () => {
[](#%5F%5Fcodelineno-5-2)  const result = await Biometrics.hasDeviceCredential();
[](#%5F%5Fcodelineno-5-3)
[](#%5F%5Fcodelineno-5-4)  if (result.hasDeviceCredential) {
[](#%5F%5Fcodelineno-5-5)    console.log('Device credential is available as fallback');
[](#%5F%5Fcodelineno-5-6)  } else {
[](#%5F%5Fcodelineno-5-7)    console.log('No device credential configured');
[](#%5F%5Fcodelineno-5-8)  }
[](#%5F%5Fcodelineno-5-9)};
`

If biometrics are not available and the user has not set up a device credential, this means that the device is completely unprotected. In this case, you may want to prohibit the use of your app on this device.

### Canceling Authentication[¶](#canceling-authentication "Permanent link")

For scenarios where you need to programmatically cancel an ongoing authentication process, use the [cancelAuthentication(...)](/docs/plugins/biometrics/#cancelauthentication) method:

`[](#%5F%5Fcodelineno-6-1)const cancelAuth = async () => {
[](#%5F%5Fcodelineno-6-2)  await Biometrics.cancelAuthentication();
[](#%5F%5Fcodelineno-6-3)};
`

This method is useful when implementing custom UI flows or handling application state changes that require interrupting the authentication process.

### Error Handling[¶](#error-handling "Permanent link")

Proper error handling is essential for a robust implementation. For this purpose, the Capacitor Biometrics API provides a set of error codes that help you identify specific issues during the authentication process. Here are some common error codes:

* `LOCKOUT`: The device is locked out due to too many failed authentication attempts.
* `NOT_ENROLLED`: The user has not enrolled any biometric data on the device.
* `SYSTEM_CANCELED`: The system canceled the authentication process, typically due to a timeout or interruption.
* `TIMEOUT`: The authentication process timed out before completion.
* `UNAVAILABLE`: Biometric authentication is not available on the device.
* `USER_CANCELED`: The user canceled the authentication process.

All error codes are defined in the `ErrorCode` enum, which you can import from the plugin:

`[](#%5F%5Fcodelineno-7-1)import { ErrorCode } from '@capawesome-team/capacitor-biometrics';
`

## Best Practices[¶](#best-practices "Permanent link")

When implementing biometric authentication with the Capacitor Biometrics API, consider these best practices:

1. **Check availability and enrollment**: Always verify that biometrics are available and enrolled before presenting biometric options to users. Use [isAvailable(...)](/docs/plugins/biometrics/#isavailable) and [isEnrolled(...)](/docs/plugins/biometrics/#isenrolled) to ensure the feature is ready for use.
2. **Provide fallback options**: Enable device credential fallback using `allowDeviceCredential: true` in your authentication calls. This ensures users can still authenticate even if biometric recognition fails or is temporarily unavailable.
3. **Handle errors gracefully**: Implement comprehensive error handling to manage different authentication scenarios. Provide clear feedback to users about authentication failures and guide them on alternative authentication methods.
4. **Customize authentication prompts**: Use descriptive titles, subtitles, and descriptions in your authentication prompts to help users understand why authentication is required and what actions they can take.
5. **Respect user preferences**: Allow users to disable biometric authentication in your app settings and provide alternative authentication methods for users who prefer not to use biometric features.

## Conclusion[¶](#conclusion "Permanent link")

The [Capacitor Biometrics](/docs/plugins/biometrics/) plugin from Capawesome provides a comprehensive solution for integrating biometric authentication into Ionic applications. By offering a unified API across multiple platforms, it enables developers to create secure and user-friendly authentication experiences without the complexity of platform-specific implementations. For the full plugin documentation, see the [API Reference](/docs/plugins/biometrics/#api).

**Related guides:**

* [Announcing the Capacitor Biometrics Plugin](/blog/announcing-the-capacitor-biometrics-plugin/)
* [How to Securely Store Credentials with Capacitor](/blog/how-to-securely-store-credentials-with-capacitor/)
* [Alternative to the Ionic Identity Vault plugin](/blog/alternative-to-ionic-identity-vault-plugin/)

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/) and follow us on [X (formerly Twitter)](https://x.com/capawesomeio).

May 7, 2026 

 Back to top