@capgo/capacitor-native-biometric
Overview
Section titled “Overview”Native Biometric is a secure credential vault for iOS and Android. It stores credentials in the native Keychain or Keystore and can require biometric authentication before sensitive values are returned. It is a direct replacement for Ionic Identity Vault credential-vault flows; your app keeps control of timeout, lifecycle, privacy-screen, and custom-passcode policies.
Core Capabilities
Section titled “Core Capabilities”setCredentialsandgetCredentials- Securely store and retrieve credentials for a given server.getSecureCredentials- Read credentials only after a native biometric check.isCredentialsSavedanddeleteCredentials- Build onboarding, locked-state, and logout flows.isAvailableandverifyIdentity- Check authentication availability and prompt the user when needed.
Public API
Section titled “Public API”| Method | Description |
|---|---|
isAvailable | Checks if biometric authentication hardware is available. |
addListener | Adds a listener that is called when the app resumes from background. This is useful to detect if biometry availability has changed while the app was in the background (e.g., user enrolled/unenrolled biometrics). |
verifyIdentity | Prompts the user to authenticate with biometrics. |
getCredentials | Gets the stored credentials for a given server. |
setCredentials | Stores the given credentials for a given server. |
deleteCredentials | Deletes the stored credentials for a given server. |
getSecureCredentials | Gets the stored credentials for a given server, requiring biometric authentication. Credentials must have been stored with accessControl set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY. |
isCredentialsSaved | Checks if credentials are already saved for a given server. |
getPluginVersion | Get the native Capacitor plugin version. |
Reference Values
Section titled “Reference Values”Use these values when handling biometricError results from authenticate.
Biometric Auth Errors
Section titled “Biometric Auth Errors”| Value | Code | Platform | Meaning |
|---|---|---|---|
UNKNOWN_ERROR | 0 | Android, iOS | Unknown error occurred. |
BIOMETRICS_UNAVAILABLE | 1 | Android, iOS | Biometrics are unavailable because hardware is missing or unavailable. |
USER_LOCKOUT | 2 | Android, iOS | User is locked out after too many failed attempts. |
BIOMETRICS_NOT_ENROLLED | 3 | Android, iOS | No biometrics are enrolled on the device. |
USER_TEMPORARY_LOCKOUT | 4 | Android | User is temporarily locked out, typically for 30 seconds. |
AUTHENTICATION_FAILED | 10 | Android, iOS | Authentication failed. |
APP_CANCEL | 11 | iOS | App canceled the authentication flow. |
INVALID_CONTEXT | 12 | iOS | Authentication context is invalid. |
NOT_INTERACTIVE | 13 | iOS | Authentication was not interactive. |
PASSCODE_NOT_SET | 14 | Android, iOS | Device passcode, PIN, or fallback credential is not set. |
SYSTEM_CANCEL | 15 | Android, iOS | System canceled authentication, for example after screen lock. |
USER_CANCEL | 16 | Android, iOS | User canceled authentication. |
USER_FALLBACK | 17 | Android, iOS | User chose fallback authentication. |
Source Of Truth
Section titled “Source Of Truth”This reference is synced from src/definitions.ts in capacitor-native-biometric.
Keep going from @capgo/capacitor-native-biometric
Section titled “Keep going from @capgo/capacitor-native-biometric”If you are using @capgo/capacitor-native-biometric to plan authentication and account flows, connect it with Using @capgo/capacitor-native-biometric for the native capability in Using @capgo/capacitor-native-biometric, @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, Two-factor authentication for the implementation detail in Two-factor authentication, and SSO (Enterprise) for the implementation detail in SSO (Enterprise).