--- description: Capacitor Vault plugin for biometric-protected, lockable secure storage on Android and iOS. A near drop-in Ionic Identity Vault alternative. title: Capacitor Vault Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/vault.png --- [Skip to content ](#capacitor-vault-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ 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/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ 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/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ 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 [ Vault ](/docs/sdks/capacitor/vault/) * [ iOS ](#ios) * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Next steps ](#next-steps) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ 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) * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Next steps ](#next-steps) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor Vault Plugin[ΒΆ](#capacitor-vault-plugin "Permanent link") Capacitor plugin to securely store key/value pairs in lockable, biometric-protected vaults. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1) ](https://capawesome.io/) ## Features[ΒΆ](#features "Permanent link") The Capacitor Vault plugin is one of the most complete secure storage solutions for Capacitor apps. Here are some of the key features: * πŸ–₯️ **Cross-platform**: Native secure vault on Android and iOS, with a `localStorage`\-backed web implementation for development. * πŸ”’ **Secure**: Hardware-backed encryption via the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and [iOS Keychain](https://developer.apple.com/documentation/security/keychain-services). * πŸ”“ **Lockable**: Unlock once with a biometric or passcode prompt, then perform many read/write operations until `lock()` is called. * ⏱️ **Auto-lock**: Automatically lock the vault after the app has been backgrounded for a configurable duration. * πŸ—‚οΈ **Multi-vault**: Create multiple independent vaults with different configurations on the same device. * πŸ” **Multiple vault types**: Authenticate with biometrics, the device passcode, or either. * ♻️ **Key invalidation**: Optionally invalidate the encryption key when the device's biometric set changes. * 🚨 **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 [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) and [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/) 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 Vault plugin is typically used whenever access to stored data should require an explicit user authentication, for example: * **App lock**: Protect sensitive parts of your app behind a biometric or device-passcode prompt. * **Password managers**: Store user credentials that are only readable after the user unlocks the vault. * **Authenticator apps**: Keep TOTP secrets locked until the user authenticates. * **Master key storage**: Protect the master password or encryption key that guards other data, such as an encrypted database. * **Session protection**: Automatically lock stored data when the app has been backgrounded for a configurable duration. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.1.x | \>=8.x.x | Active support | ## Demo[ΒΆ](#demo "Permanent link") A working example can be found [here](https://github.com/capawesome-team/capacitor-vault-demo). | Android | iOS | | ------- | --- | ## Guides[ΒΆ](#guides "Permanent link") * [Announcing the Capacitor Vault Plugin](https://capawesome.io/blog/announcing-the-capacitor-vault-plugin/) * [Alternatives to Ionic Enterprise Plugins](https://capawesome.io/blog/alternatives-to-ionic-enterprise-plugins/) * [Alternative to the Ionic Identity Vault Plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/) ## Videos[ΒΆ](#videos "Permanent link") * [How to Secure Sensitive Data Using Capacitor Vault Plugin](https://youtu.be/wCNMqVBnQqs?si=mePC0ADiRHy%5FrFQz) ## 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-vault` 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-vault [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Minimum Android version[ΒΆ](#minimum-android-version "Permanent link") The `DEVICE_PASSCODE` and `BIOMETRIC_OR_DEVICE_PASSCODE` vault types require Android API 30 (Android 11) or higher. On lower versions, `initialize(...)` will reject with the `AUTHENTICATOR_UNAVAILABLE` error code. The `BIOMETRIC` vault type is supported on all supported Android versions. #### 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 variables in your app's `variables.gradle` file to change the default version of the dependencies: * `$androidxBiometricVersion` version of `androidx.biometric:biometric` (default: `1.1.0`) * `$androidxLifecycleProcessVersion` version of `androidx.lifecycle:lifecycle-process` (default: `2.9.4`) 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 Face ID: `[](#%5F%5Fcodelineno-5-1)NSFaceIDUsageDescription [](#%5F%5Fcodelineno-5-2)This app uses Face ID to unlock your data. ` ### Web[ΒΆ](#web "Permanent link") **Attention**: The web implementation uses `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to initialize a vault, check whether one exists, unlock and lock it, store and retrieve values, clear or destroy it, and listen for lock and unlock events. ### Initialize the vault[ΒΆ](#initialize-the-vault "Permanent link") Initialize the vault with the desired configuration once per session before calling any other method. The `lockAfterBackgrounded` option automatically locks the vault after the app has been backgrounded for the given duration in milliseconds: `[](#%5F%5Fcodelineno-6-1)import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)// Call once per session before any other method. [](#%5F%5Fcodelineno-6-4)const initialize = async () => { [](#%5F%5Fcodelineno-6-5) await Vault.initialize({ [](#%5F%5Fcodelineno-6-6) type: VaultType.Biometric, [](#%5F%5Fcodelineno-6-7) title: 'Unlock vault', [](#%5F%5Fcodelineno-6-8) cancelButtonText: 'Cancel', [](#%5F%5Fcodelineno-6-9) iosFallbackButtonText: 'Use Passcode', [](#%5F%5Fcodelineno-6-10) lockAfterBackgrounded: 30000, [](#%5F%5Fcodelineno-6-11) }); [](#%5F%5Fcodelineno-6-12)}; ` ### Check whether a vault exists[ΒΆ](#check-whether-a-vault-exists "Permanent link") Check whether a vault was created in a previous session, for example to decide between a fresh setup and an unlock flow: `[](#%5F%5Fcodelineno-7-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)// Check whether a vault was created in a previous session. [](#%5F%5Fcodelineno-7-4)const exists = async () => { [](#%5F%5Fcodelineno-7-5) const { exists } = await Vault.exists(); [](#%5F%5Fcodelineno-7-6) return exists; [](#%5F%5Fcodelineno-7-7)}; ` ### Unlock and lock the vault[ΒΆ](#unlock-and-lock-the-vault "Permanent link") Unlocking prompts the user for biometric authentication or the device credential, depending on the vault's type. Once unlocked, you can perform many read and write operations until the vault is locked again: `[](#%5F%5Fcodelineno-8-1)import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)// Prompt the user for biometric authentication. [](#%5F%5Fcodelineno-8-4)const unlock = async () => { [](#%5F%5Fcodelineno-8-5) try { [](#%5F%5Fcodelineno-8-6) await Vault.unlock(); [](#%5F%5Fcodelineno-8-7) } catch (error) { [](#%5F%5Fcodelineno-8-8) if (error.code === ErrorCode.UnlockCanceled) { [](#%5F%5Fcodelineno-8-9) console.log('The user canceled the authentication prompt.'); [](#%5F%5Fcodelineno-8-10) } else if (error.code === ErrorCode.KeyInvalidated) { [](#%5F%5Fcodelineno-8-11) console.log('The encryption key was invalidated.'); [](#%5F%5Fcodelineno-8-12) } else { [](#%5F%5Fcodelineno-8-13) console.log('Another error occurred:', error); [](#%5F%5Fcodelineno-8-14) } [](#%5F%5Fcodelineno-8-15) } [](#%5F%5Fcodelineno-8-16)}; [](#%5F%5Fcodelineno-8-17) [](#%5F%5Fcodelineno-8-18)// Check whether the vault is currently locked. [](#%5F%5Fcodelineno-8-19)const isLocked = async () => { [](#%5F%5Fcodelineno-8-20) const { isLocked } = await Vault.isLocked(); [](#%5F%5Fcodelineno-8-21) return isLocked; [](#%5F%5Fcodelineno-8-22)}; [](#%5F%5Fcodelineno-8-23) [](#%5F%5Fcodelineno-8-24)// Lock the vault manually. [](#%5F%5Fcodelineno-8-25)const lock = async () => { [](#%5F%5Fcodelineno-8-26) await Vault.lock(); [](#%5F%5Fcodelineno-8-27)}; ` ### Store and retrieve values[ΒΆ](#store-and-retrieve-values "Permanent link") Store, retrieve, and remove key/value pairs. The vault must be unlocked before calling these methods: `[](#%5F%5Fcodelineno-9-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)// Store a value. [](#%5F%5Fcodelineno-9-4)const setValue = async () => { [](#%5F%5Fcodelineno-9-5) await Vault.setValue({ key: 'token', value: 'abc123' }); [](#%5F%5Fcodelineno-9-6)}; [](#%5F%5Fcodelineno-9-7) [](#%5F%5Fcodelineno-9-8)// Retrieve a value. [](#%5F%5Fcodelineno-9-9)const getValue = async () => { [](#%5F%5Fcodelineno-9-10) const { value } = await Vault.getValue({ key: 'token' }); [](#%5F%5Fcodelineno-9-11) return value; [](#%5F%5Fcodelineno-9-12)}; [](#%5F%5Fcodelineno-9-13) [](#%5F%5Fcodelineno-9-14)// Remove a single value. [](#%5F%5Fcodelineno-9-15)const removeValue = async () => { [](#%5F%5Fcodelineno-9-16) await Vault.removeValue({ key: 'token' }); [](#%5F%5Fcodelineno-9-17)}; [](#%5F%5Fcodelineno-9-18) [](#%5F%5Fcodelineno-9-19)// List all keys currently stored in the vault. [](#%5F%5Fcodelineno-9-20)const getKeys = async () => { [](#%5F%5Fcodelineno-9-21) const { keys } = await Vault.getKeys(); [](#%5F%5Fcodelineno-9-22) return keys; [](#%5F%5Fcodelineno-9-23)}; ` ### Clear or destroy the vault[ΒΆ](#clear-or-destroy-the-vault "Permanent link") Remove all values while preserving the vault's configuration, or destroy the vault entirely so that it must be reinitialized before use: `[](#%5F%5Fcodelineno-10-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)// Remove all values without destroying the vault. [](#%5F%5Fcodelineno-10-4)const clear = async () => { [](#%5F%5Fcodelineno-10-5) await Vault.clear(); [](#%5F%5Fcodelineno-10-6)}; [](#%5F%5Fcodelineno-10-7) [](#%5F%5Fcodelineno-10-8)// Permanently destroy the vault. [](#%5F%5Fcodelineno-10-9)const destroy = async () => { [](#%5F%5Fcodelineno-10-10) await Vault.destroy(); [](#%5F%5Fcodelineno-10-11)}; ` ### Listen for lock and unlock events[ΒΆ](#listen-for-lock-and-unlock-events "Permanent link") React to the vault being locked or unlocked, for example to navigate to a lock screen when the vault locks: `` [](#%5F%5Fcodelineno-11-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-11-2) [](#%5F%5Fcodelineno-11-3)// React to lock and unlock events. [](#%5F%5Fcodelineno-11-4)const addListeners = async () => { [](#%5F%5Fcodelineno-11-5) await Vault.addListener('lock', ({ vaultId, trigger }) => { [](#%5F%5Fcodelineno-11-6) console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`); [](#%5F%5Fcodelineno-11-7) }); [](#%5F%5Fcodelineno-11-8) await Vault.addListener('unlock', ({ vaultId }) => { [](#%5F%5Fcodelineno-11-9) console.log(`Vault ${vaultId} unlocked.`); [](#%5F%5Fcodelineno-11-10) }); [](#%5F%5Fcodelineno-11-11)}; `` ## API[ΒΆ](#api "Permanent link") * [clear(...)](#clear) * [destroy(...)](#destroy) * [exists(...)](#exists) * [exportData(...)](#exportdata) * [getKeys(...)](#getkeys) * [getValue(...)](#getvalue) * [importData(...)](#importdata) * [initialize(...)](#initialize) * [isEmpty(...)](#isempty) * [isLocked(...)](#islocked) * [lock(...)](#lock) * [removeValue(...)](#removevalue) * [setValue(...)](#setvalue) * [unlock(...)](#unlock) * [addListener('lock', ...)](#addlistenerlock-) * [addListener('unlock', ...)](#addlistenerunlock-) * [removeAllListeners()](#removealllisteners) * [Interfaces](#interfaces) * [Enums](#enums) ### clear(...)[ΒΆ](#clear "Permanent link") `[](#%5F%5Fcodelineno-12-1)clear(options?: ClearOptions | undefined) => Promise ` Remove all values from the vault while preserving its configuration. The vault must be unlocked before calling this method. | Param | Type | | ----------- | ----------------------------- | | **options** | [ClearOptions](#clearoptions) | **Since:** 0.1.0 --- ### destroy(...)[ΒΆ](#destroy "Permanent link") `[](#%5F%5Fcodelineno-13-1)destroy(options?: DestroyOptions | undefined) => Promise ` Destroy the vault, removing all values and its configuration. After calling this method, the vault must be reinitialized before use. | Param | Type | | ----------- | --------------------------------- | | **options** | [DestroyOptions](#destroyoptions) | **Since:** 0.1.0 --- ### exists(...)[ΒΆ](#exists "Permanent link") `[](#%5F%5Fcodelineno-14-1)exists(options?: ExistsOptions | undefined) => Promise ` Check whether a vault with the given identifier exists on the device. Returns `true` for any vault that was previously created and has not been destroyed, even if `initialize()` has not been called in the current session. Useful for detecting whether a fresh setup or an unlock flow is required. | Param | Type | | ----------- | ------------------------------- | | **options** | [ExistsOptions](#existsoptions) | **Returns:** `Promise<[ExistsResult](#existsresult)>` **Since:** 0.1.0 --- ### exportData(...)[ΒΆ](#exportdata "Permanent link") `[](#%5F%5Fcodelineno-15-1)exportData(options?: ExportDataOptions | undefined) => Promise ` Export all values from the vault as a key/value map. The vault must be unlocked before calling this method. **Note**: Designed for small datasets such as backup/restore flows. The entire set of values is loaded into memory and serialized across the Capacitor bridge in a single call. Avoid using this method on vaults with large amounts of data to prevent out-of-memory errors. | Param | Type | | ----------- | --------------------------------------- | | **options** | [ExportDataOptions](#exportdataoptions) | **Returns:** `Promise<[ExportDataResult](#exportdataresult)>` **Since:** 0.1.0 --- ### getKeys(...)[ΒΆ](#getkeys "Permanent link") `[](#%5F%5Fcodelineno-16-1)getKeys(options?: GetKeysOptions | undefined) => Promise ` Get a list of all keys stored in the vault. The vault must be unlocked before calling this method. | Param | Type | | ----------- | --------------------------------- | | **options** | [GetKeysOptions](#getkeysoptions) | **Returns:** `Promise<[GetKeysResult](#getkeysresult)>` **Since:** 0.1.0 --- ### getValue(...)[ΒΆ](#getvalue "Permanent link") `[](#%5F%5Fcodelineno-17-1)getValue(options: GetValueOptions) => Promise ` Get the value associated with a key. The vault must be unlocked before calling this method. | Param | Type | | ----------- | ----------------------------------- | | **options** | [GetValueOptions](#getvalueoptions) | **Returns:** `Promise<[GetValueResult](#getvalueresult)>` **Since:** 0.1.0 --- ### importData(...)[ΒΆ](#importdata "Permanent link") `[](#%5F%5Fcodelineno-18-1)importData(options: ImportDataOptions) => Promise ` Import a key/value map into the vault, replacing all existing values. The vault must be unlocked before calling this method. Any values previously stored in the vault are removed before the new entries are written. On partial failure, the vault may be left in an inconsistent state β€” callers that need atomicity should call `exportData()` first and re-import on failure. **Note**: Designed for small datasets such as backup/restore flows. The entire set of values is loaded into memory and serialized across the Capacitor bridge in a single call. Avoid using this method on vaults with large amounts of data to prevent out-of-memory errors. | Param | Type | | ----------- | --------------------------------------- | | **options** | [ImportDataOptions](#importdataoptions) | **Since:** 0.1.0 --- ### initialize(...)[ΒΆ](#initialize "Permanent link") `[](#%5F%5Fcodelineno-19-1)initialize(options: InitializeOptions) => Promise ` Initialize a vault with the given configuration. Must be called once per session before any other method. The `type` and `invalidateOnBiometricEnrollment` options are baked into the encryption key at vault creation and cannot be changed afterwards; values passed for existing vaults are silently ignored. | Param | Type | | ----------- | --------------------------------------- | | **options** | [InitializeOptions](#initializeoptions) | **Since:** 0.1.0 --- ### isEmpty(...)[ΒΆ](#isempty "Permanent link") `[](#%5F%5Fcodelineno-20-1)isEmpty(options?: IsEmptyOptions | undefined) => Promise ` Check whether the vault contains no values. | Param | Type | | ----------- | --------------------------------- | | **options** | [IsEmptyOptions](#isemptyoptions) | **Returns:** `Promise<[IsEmptyResult](#isemptyresult)>` **Since:** 0.1.0 --- ### isLocked(...)[ΒΆ](#islocked "Permanent link") `[](#%5F%5Fcodelineno-21-1)isLocked(options?: IsLockedOptions | undefined) => Promise ` Check whether the vault is currently locked. Rejects with `VAULT_NOT_FOUND` if the vault has not been initialized in the current session. | Param | Type | | ----------- | ----------------------------------- | | **options** | [IsLockedOptions](#islockedoptions) | **Returns:** `Promise<[IsLockedResult](#islockedresult)>` **Since:** 0.1.0 --- ### lock(...)[ΒΆ](#lock "Permanent link") `[](#%5F%5Fcodelineno-22-1)lock(options?: LockOptions | undefined) => Promise ` Lock the vault. Clears the in-memory encryption key. Stored values remain encrypted on disk and are recoverable via `unlock()`. | Param | Type | | ----------- | --------------------------- | | **options** | [LockOptions](#lockoptions) | **Since:** 0.1.0 --- ### removeValue(...)[ΒΆ](#removevalue "Permanent link") `[](#%5F%5Fcodelineno-23-1)removeValue(options: RemoveValueOptions) => Promise ` Remove the value associated with a key. The vault must be unlocked before calling this method. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [RemoveValueOptions](#removevalueoptions) | **Since:** 0.1.0 --- ### setValue(...)[ΒΆ](#setvalue "Permanent link") `[](#%5F%5Fcodelineno-24-1)setValue(options: SetValueOptions) => Promise ` Set the value associated with a key. The vault must be unlocked before calling this method. On **Web**, the value is stored unencrypted in `localStorage`. This is for development purposes only and should NOT be used in production. | Param | Type | | ----------- | ----------------------------------- | | **options** | [SetValueOptions](#setvalueoptions) | **Since:** 0.1.0 --- ### unlock(...)[ΒΆ](#unlock "Permanent link") `[](#%5F%5Fcodelineno-25-1)unlock(options?: UnlockOptions | undefined) => Promise ` Unlock the vault. Prompts the user for biometric authentication or device credential, depending on the vault's `type`. | Param | Type | | ----------- | ------------------------------- | | **options** | [UnlockOptions](#unlockoptions) | **Since:** 0.1.0 --- ### addListener('lock', ...)[ΒΆ](#addlistenerlock "Permanent link") `[](#%5F%5Fcodelineno-26-1)addListener(eventName: 'lock', listenerFunc: (event: LockEvent) => void) => Promise ` Add a listener for vault events. | Param | Type | | ---------------- | ---------------------------------------- | | **eventName** | 'lock' | | **listenerFunc** | (event: [LockEvent](#lockevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### addListener('unlock', ...)[ΒΆ](#addlistenerunlock "Permanent link") `[](#%5F%5Fcodelineno-27-1)addListener(eventName: 'unlock', listenerFunc: (event: UnlockEvent) => void) => Promise ` Add a listener for vault events. | Param | Type | | ---------------- | -------------------------------------------- | | **eventName** | 'unlock' | | **listenerFunc** | (event: [UnlockEvent](#unlockevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link") `[](#%5F%5Fcodelineno-28-1)removeAllListeners() => Promise ` Remove all listeners registered for this plugin. **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### ClearOptions[ΒΆ](#clearoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### DestroyOptions[ΒΆ](#destroyoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### ExistsResult[ΒΆ](#existsresult "Permanent link") | Prop | Type | Description | Since | | ---------- | ------- | ---------------------------------------------- | ----- | | **exists** | boolean | Whether or not the vault has been initialized. | 0.1.0 | #### ExistsOptions[ΒΆ](#existsoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### ExportDataResult[ΒΆ](#exportdataresult "Permanent link") | Prop | Type | Description | Since | | -------- | ---------------------------- | --------------------------- | ----- | | **data** | { \[key: string\]: string; } | The exported key/value map. | 0.1.0 | #### ExportDataOptions[ΒΆ](#exportdataoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### GetKeysResult[ΒΆ](#getkeysresult "Permanent link") | Prop | Type | Description | Since | | -------- | ---------- | --------------------------------------- | ----- | | **keys** | string\[\] | The keys currently stored in the vault. | 0.1.0 | #### GetKeysOptions[ΒΆ](#getkeysoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### GetValueResult[ΒΆ](#getvalueresult "Permanent link") | Prop | Type | Description | Since | | --------- | -------------- | -------------------------------------------------------------------- | ----- | | **value** | string \| null | The retrieved value, or null if no value is associated with the key. | 0.1.0 | #### GetValueOptions[ΒΆ](#getvalueoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ----------------------------------------- | --------- | ----- | | **key** | string | The key associated with the stored value. | | 0.1.0 | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### ImportDataOptions[ΒΆ](#importdataoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ---------------------------- | -------------------------------------------------------------------------------------- | --------- | ----- | | **data** | { \[key: string\]: string; } | The key/value map to import into the vault. Replaces all existing values in the vault. | | 0.1.0 | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### InitializeOptions[ΒΆ](#initializeoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----- | | **cancelButtonText** | string | The text displayed on the cancel button of the authentication prompt. Only available on Android and iOS. | | 0.1.0 | | **invalidateOnBiometricEnrollment** | boolean | Whether the encryption key should be invalidated when the device's biometric set changes (e.g., a new fingerprint or face is enrolled). If true and the biometric set changes, the next unlock() call rejects with KEY\_INVALIDATED. The app must call destroy() and reinitialize. Per-platform behavior: - **Android**: when biometric is involved, invalidates the entire encryption key. For BIOMETRIC\_OR\_DEVICE\_PASSCODE vaults, the device passcode path is also rendered unusable. - **iOS**: when biometric is involved, invalidates the biometric branch only. For BIOMETRIC\_OR\_DEVICE\_PASSCODE vaults, the user can still unlock with the device passcode. Only applies to vault types that use biometric authentication. **Note**: This option is baked into the encryption key at vault creation time. The value passed when reinitializing an existing vault is silently ignored. | false | 0.1.0 | | **iosFallbackButtonText** | string | The text displayed on the fallback button of the authentication prompt. Only available on iOS. | | 0.1.0 | | **lockAfterBackgrounded** | number | The duration in milliseconds the app must be backgrounded before the vault is automatically locked. If omitted, the vault is never automatically locked. | | 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 | | **type** | [VaultType](#vaulttype) | The type of the vault. | | 0.1.0 | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### IsEmptyResult[ΒΆ](#isemptyresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ------- | ------------------------------------- | ----- | | **isEmpty** | boolean | Whether the vault contains no values. | 0.1.0 | #### IsEmptyOptions[ΒΆ](#isemptyoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### IsLockedResult[ΒΆ](#islockedresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ------- | -------------------------------------- | ----- | | **isLocked** | boolean | Whether the vault is currently locked. | 0.1.0 | #### IsLockedOptions[ΒΆ](#islockedoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### LockOptions[ΒΆ](#lockoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### RemoveValueOptions[ΒΆ](#removevalueoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ----------------------------------------- | --------- | ----- | | **key** | string | The key associated with the stored value. | | 0.1.0 | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### SetValueOptions[ΒΆ](#setvalueoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ----------------------------------------- | --------- | ----- | | **key** | string | The key associated with the stored value. | | 0.1.0 | | **value** | string | The value to store. | | 0.1.0 | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### UnlockOptions[ΒΆ](#unlockoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------- | ------ | ---------------------------- | --------- | ----- | | **vaultId** | string | The identifier of the vault. | 'default' | 0.1.0 | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | #### LockEvent[ΒΆ](#lockevent "Permanent link") | Prop | Type | Description | Since | | ----------- | --------------------------- | ---------------------------------------- | ----- | | **trigger** | [LockTrigger](#locktrigger) | What caused the vault to lock. | 0.1.0 | | **vaultId** | string | The identifier of the vault that locked. | 0.1.0 | #### UnlockEvent[ΒΆ](#unlockevent "Permanent link") | Prop | Type | Description | Since | | ----------- | ------ | ------------------------------------------ | ----- | | **vaultId** | string | The identifier of the vault that unlocked. | 0.1.0 | ### Enums[ΒΆ](#enums "Permanent link") #### VaultType[ΒΆ](#vaulttype "Permanent link") | Members | Value | Description | Since | | ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **Biometric** | 'BIOMETRIC' | The vault is unlocked with the device's biometric authentication. Requires a Class 3 (Strong) biometric sensor on Android. Initialization rejects with AUTHENTICATOR\_UNAVAILABLE if no Strong biometric is available. | 0.1.0 | | **BiometricOrDevicePasscode** | 'BIOMETRIC\_OR\_DEVICE\_PASSCODE' | The vault is unlocked with either the device's biometric authentication or the device's credential (PIN, pattern, or password). | 0.1.0 | | **DevicePasscode** | 'DEVICE\_PASSCODE' | The vault is unlocked with the device's credential (PIN, pattern, or password). | 0.1.0 | #### LockTrigger[ΒΆ](#locktrigger "Permanent link") | Members | Value | Description | Since | | ----------- | --------- | ---------------------------------------------------------------------------------------- | ----- | | **Manual** | 'MANUAL' | The vault was locked by an explicit call to lock(). | 0.1.0 | | **Timeout** | 'TIMEOUT' | The vault was locked because the app was backgrounded longer than lockAfterBackgrounded. | 0.1.0 | ## FAQ[ΒΆ](#faq "Permanent link") ### Where is the data stored?[ΒΆ](#where-is-the-data-stored "Permanent link") On Android, the encryption key is stored in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and the encrypted values are stored in two `SharedPreferences` files per vault. On iOS, both the encryption key and the encrypted values are stored as separate [Keychain](https://developer.apple.com/documentation/security/keychain-services) items. The encryption key is never included in cloud backups on either platform. On Android, the encrypted values in `SharedPreferences` are part of [Android Auto Backup](https://developer.android.com/identity/data/autobackup) by default, but the backed-up ciphertext is unusable on another device without the Keystore key; to exclude the preference files (`capawesome_capacitor_vault_key_.xml` and `capawesome_capacitor_vault_data_.xml`) from backup, see the [Android documentation](https://developer.android.com/identity/data/autobackup#IncludingFiles). On iOS, the Keychain items use the `*ThisDeviceOnly` accessibility classes, so they are never synced to iCloud Keychain or included in device backups. ### When should I use Vault instead of Secure Preferences or SQLite?[ΒΆ](#when-should-i-use-vault-instead-of-secure-preferences-or-sqlite "Permanent link") All three plugins protect data on the device, but they target different problems: * **[Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/)** is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background β€” typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information. * **[SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/)** is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets β€” for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database. * **Vault** (this plugin) is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action β€” a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an "app lock" screen. A quick decision tree: * Need queries, relations, or large datasets? β†’ **SQLite**. * Need encrypted key/value storage the app can read freely in the background? β†’ **Secure Preferences**. * Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? β†’ **Vault**. The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else. ### Is this plugin an alternative to Ionic Identity Vault?[ΒΆ](#is-this-plugin-an-alternative-to-ionic-identity-vault "Permanent link") Yes. This plugin was built as an alternative to [Ionic Identity Vault](https://ionic.io/products/identity-vault) and offers a similar feature set: * Hardware-backed encryption using the Android Keystore and iOS Keychain * Biometric, device passcode, or combined authentication * Lockable session model with manual lock and auto-lock on background * Multiple independent vaults per device * Key invalidation when the device's biometric set changes ### How do I migrate from Ionic Identity Vault?[ΒΆ](#how-do-i-migrate-from-ionic-identity-vault "Permanent link") For an AI-assisted migration of your code, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool and use the `ionic-enterprise-sdk-migration` skill to migrate your project to `@capawesome-team/capacitor-vault`. Alternatively, you can follow the manual instructions and the complete runtime migration example in the blog post [Alternative to the Ionic Identity Vault plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/). The stored data needs to be migrated at runtime while **both** plugins are still installed: Identity Vault exposes `exportVault()`, which returns a plain key/value map after the user unlocks the vault, and that map has the exact shape expected by this plugin's [importData(...)](#importdata) method, so the two can be bridged directly. Note that the user has to authenticate once during the migration to unlock the old vault β€” this is unavoidable, since the data is protected by the device's biometric or passcode authentication by design. Once all users have migrated (for example, after a release cycle in which everyone has opened the app at least once), you can remove the Identity Vault dependency in a follow-up release. ### What happens when the user enrolls a new fingerprint or face?[ΒΆ](#what-happens-when-the-user-enrolls-a-new-fingerprint-or-face "Permanent link") If the vault was created with the `invalidateOnBiometricEnrollment` option set to `true`, the encryption key is invalidated when the device's biometric set changes, and the next `unlock()` call rejects with the `KEY_INVALIDATED` error code. The app must then call `destroy()` and reinitialize the vault. On Android, the entire encryption key is invalidated, while on iOS only the biometric branch is invalidated, so users of `BIOMETRIC_OR_DEVICE_PASSCODE` vaults can still unlock with the device passcode. Note that this option is baked into the encryption key at vault creation time and cannot be changed afterwards. ### Can I use this plugin on the Web?[ΒΆ](#can-i-use-this-plugin-on-the-web "Permanent link") The web implementation stores values unencrypted in `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production. The secure, hardware-backed vault is only available on Android and iOS. ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face recognition or fingerprint recognition. * [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords, tokens or other sensitive information. * [SQLite](https://capawesome.io/docs/sdks/capacitor/sqlite/): Access SQLite databases with support for encryption, transactions, and schema migrations. ## Next steps[ΒΆ](#next-steps "Permanent link") Here are a few resources to help you continue: * Read [Alternative to the Ionic Identity Vault plugin](https://capawesome.io/blog/alternative-to-ionic-identity-vault-plugin/) if you are migrating from Ionic Identity Vault. * Need simple secure key/value storage without vault locking? Check out the [Capacitor Secure Preferences plugin](https://capawesome.io/docs/sdks/capacitor/secure-preferences/). * Check out [Getting Started with Insiders](https://capawesome.io/docs/insiders/getting-started/) to learn how to install the plugin. ## 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://capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/vault/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/vault/#article", "headline": "Capacitor Vault Plugin for Android & iOS", "name": "Capacitor Vault Plugin for Android & iOS", "description": "Capacitor Vault plugin for biometric-protected, lockable secure storage on Android and iOS. A near drop-in Ionic Identity Vault alternative.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/vault/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/vault/", "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/vault/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/vault/#software", "name": "Capacitor Vault Plugin for Android & iOS", "description": "Capacitor Vault plugin for biometric-protected, lockable secure storage on Android and iOS. A near drop-in Ionic Identity Vault alternative.", "url": "https://capawesome.io/docs/sdks/capacitor/vault/", "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": "Where is the data stored?", "acceptedAnswer": {"@type": "Answer", "text": "On Android, the encryption key is stored in the Android Keystore and the encrypted values are stored in two SharedPreferences files per vault. On iOS, both the encryption key and the encrypted values are stored as separate Keychain items. The encryption key is never included in cloud backups on either platform. On Android, the encrypted values in SharedPreferences are part of Android Auto Backup by default, but the backed-up ciphertext is unusable on another device without the Keystore key; to exclude the preference files ( capawesome_capacitor_vault_key_.xml and capawesome_capacitor_vault_data_.xml) from backup, see the Android documentation. On iOS, the Keychain items use the *ThisDeviceOnly accessibility classes, so they are never synced to iCloud Keychain or included in device backups."}}, {"@type": "Question", "name": "When should I use Vault instead of Secure Preferences or SQLite?", "acceptedAnswer": {"@type": "Answer", "text": "All three plugins protect data on the device, but they target different problems: Secure Preferences is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background β€” typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information. SQLite is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets β€” for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database. Vault (this plugin) is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action β€” a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an \"app lock\" screen. A quick decision tree: Need queries, relations, or large datasets? β†’ SQLite. Need encrypted key/value storage the app can read freely in the background? β†’ Secure Preferences. Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? β†’ Vault. The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else."}}, {"@type": "Question", "name": "Is this plugin an alternative to Ionic Identity Vault?", "acceptedAnswer": {"@type": "Answer", "text": "Yes. This plugin was built as an alternative to Ionic Identity Vault and offers a similar feature set: Hardware-backed encryption using the Android Keystore and iOS Keychain Biometric, device passcode, or combined authentication Lockable session model with manual lock and auto-lock on background Multiple independent vaults per device Key invalidation when the device's biometric set changes"}}, {"@type": "Question", "name": "How do I migrate from Ionic Identity Vault?", "acceptedAnswer": {"@type": "Answer", "text": "For an AI-assisted migration of your code, add the Capawesome Skills to your AI tool and use the ionic-enterprise-sdk-migration skill to migrate your project to @capawesome-team/capacitor-vault. Alternatively, you can follow the manual instructions and the complete runtime migration example in the blog post Alternative to the Ionic Identity Vault plugin. The stored data needs to be migrated at runtime while both plugins are still installed: Identity Vault exposes exportVault(), which returns a plain key/value map after the user unlocks the vault, and that map has the exact shape expected by this plugin's importData(...) method, so the two can be bridged directly. Note that the user has to authenticate once during the migration to unlock the old vault β€” this is unavoidable, since the data is protected by the device's biometric or passcode authentication by design. Once all users have migrated (for example, after a release cycle in which everyone has opened the app at least once), you can remove the Identity Vault dependency in a follow-up release."}}, {"@type": "Question", "name": "What happens when the user enrolls a new fingerprint or face?", "acceptedAnswer": {"@type": "Answer", "text": "If the vault was created with the invalidateOnBiometricEnrollment option set to true, the encryption key is invalidated when the device's biometric set changes, and the next unlock() call rejects with the KEY_INVALIDATED error code. The app must then call destroy() and reinitialize the vault. On Android, the entire encryption key is invalidated, while on iOS only the biometric branch is invalidated, so users of BIOMETRIC_OR_DEVICE_PASSCODE vaults can still unlock with the device passcode. Note that this option is baked into the encryption key at vault creation time and cannot be changed afterwards."}}, {"@type": "Question", "name": "Can I use this plugin on the Web?", "acceptedAnswer": {"@type": "Answer", "text": "The web implementation stores values unencrypted in localStorage to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production. The secure, hardware-backed vault is only available on Android and iOS."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/vault/"} ```