--- description: Capacitor Vault plugin to securely store key/value pairs in lockable, biometric-protected vaults on Android and iOS. title: Capacitor Vault Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/plugins/vault.png --- [ Skip to content](#capawesome-teamcapacitor-vault) [ πŸ” Introducing the **Capacitor Vault** plugin β€” store secrets behind biometrics or a device passcode.](/blog/announcing-the-capacitor-vault-plugin/) * [ 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/) * Vault [ Vault ](/docs/plugins/vault/) * [ iOS ](#ios) * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ 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) * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # @capawesome-team/capacitor-vault[ΒΆ](#capawesome-teamcapacitor-vault "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](../../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 secure, lockable storage. 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/plugins/biometrics/) and [Secure Preferences](https://capawesome.io/docs/plugins/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! ## 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.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") `` [](#%5F%5Fcodelineno-6-1)import { [](#%5F%5Fcodelineno-6-2) Vault, [](#%5F%5Fcodelineno-6-3) VaultType, [](#%5F%5Fcodelineno-6-4) ErrorCode, [](#%5F%5Fcodelineno-6-5)} from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-6-6) [](#%5F%5Fcodelineno-6-7)// Call once per session before any other method. [](#%5F%5Fcodelineno-6-8)const initialize = async () => { [](#%5F%5Fcodelineno-6-9) await Vault.initialize({ [](#%5F%5Fcodelineno-6-10) type: VaultType.Biometric, [](#%5F%5Fcodelineno-6-11) title: 'Unlock vault', [](#%5F%5Fcodelineno-6-12) cancelButtonText: 'Cancel', [](#%5F%5Fcodelineno-6-13) iosFallbackButtonText: 'Use Passcode', [](#%5F%5Fcodelineno-6-14) lockAfterBackgrounded: 30000, [](#%5F%5Fcodelineno-6-15) }); [](#%5F%5Fcodelineno-6-16)}; [](#%5F%5Fcodelineno-6-17) [](#%5F%5Fcodelineno-6-18)// Check whether a vault was created in a previous session. [](#%5F%5Fcodelineno-6-19)const exists = async () => { [](#%5F%5Fcodelineno-6-20) const { exists } = await Vault.exists(); [](#%5F%5Fcodelineno-6-21) return exists; [](#%5F%5Fcodelineno-6-22)}; [](#%5F%5Fcodelineno-6-23) [](#%5F%5Fcodelineno-6-24)// Prompt the user for biometric authentication. [](#%5F%5Fcodelineno-6-25)const unlock = async () => { [](#%5F%5Fcodelineno-6-26) try { [](#%5F%5Fcodelineno-6-27) await Vault.unlock(); [](#%5F%5Fcodelineno-6-28) } catch (error) { [](#%5F%5Fcodelineno-6-29) if (error.code === ErrorCode.UnlockCanceled) { [](#%5F%5Fcodelineno-6-30) console.log('The user canceled the authentication prompt.'); [](#%5F%5Fcodelineno-6-31) } else if (error.code === ErrorCode.KeyInvalidated) { [](#%5F%5Fcodelineno-6-32) console.log('The encryption key was invalidated.'); [](#%5F%5Fcodelineno-6-33) } else { [](#%5F%5Fcodelineno-6-34) console.log('Another error occurred:', error); [](#%5F%5Fcodelineno-6-35) } [](#%5F%5Fcodelineno-6-36) } [](#%5F%5Fcodelineno-6-37)}; [](#%5F%5Fcodelineno-6-38) [](#%5F%5Fcodelineno-6-39)// Check whether the vault is currently locked. [](#%5F%5Fcodelineno-6-40)const isLocked = async () => { [](#%5F%5Fcodelineno-6-41) const { isLocked } = await Vault.isLocked(); [](#%5F%5Fcodelineno-6-42) return isLocked; [](#%5F%5Fcodelineno-6-43)}; [](#%5F%5Fcodelineno-6-44) [](#%5F%5Fcodelineno-6-45)// Store a value. [](#%5F%5Fcodelineno-6-46)const setValue = async () => { [](#%5F%5Fcodelineno-6-47) await Vault.setValue({ key: 'token', value: 'abc123' }); [](#%5F%5Fcodelineno-6-48)}; [](#%5F%5Fcodelineno-6-49) [](#%5F%5Fcodelineno-6-50)// Retrieve a value. [](#%5F%5Fcodelineno-6-51)const getValue = async () => { [](#%5F%5Fcodelineno-6-52) const { value } = await Vault.getValue({ key: 'token' }); [](#%5F%5Fcodelineno-6-53) return value; [](#%5F%5Fcodelineno-6-54)}; [](#%5F%5Fcodelineno-6-55) [](#%5F%5Fcodelineno-6-56)// Remove a single value. [](#%5F%5Fcodelineno-6-57)const removeValue = async () => { [](#%5F%5Fcodelineno-6-58) await Vault.removeValue({ key: 'token' }); [](#%5F%5Fcodelineno-6-59)}; [](#%5F%5Fcodelineno-6-60) [](#%5F%5Fcodelineno-6-61)// List all keys currently stored in the vault. [](#%5F%5Fcodelineno-6-62)const getKeys = async () => { [](#%5F%5Fcodelineno-6-63) const { keys } = await Vault.getKeys(); [](#%5F%5Fcodelineno-6-64) return keys; [](#%5F%5Fcodelineno-6-65)}; [](#%5F%5Fcodelineno-6-66) [](#%5F%5Fcodelineno-6-67)// Remove all values without destroying the vault. [](#%5F%5Fcodelineno-6-68)const clear = async () => { [](#%5F%5Fcodelineno-6-69) await Vault.clear(); [](#%5F%5Fcodelineno-6-70)}; [](#%5F%5Fcodelineno-6-71) [](#%5F%5Fcodelineno-6-72)// Lock the vault manually. [](#%5F%5Fcodelineno-6-73)const lock = async () => { [](#%5F%5Fcodelineno-6-74) await Vault.lock(); [](#%5F%5Fcodelineno-6-75)}; [](#%5F%5Fcodelineno-6-76) [](#%5F%5Fcodelineno-6-77)// React to lock and unlock events. [](#%5F%5Fcodelineno-6-78)const addListeners = async () => { [](#%5F%5Fcodelineno-6-79) await Vault.addListener('lock', ({ vaultId, trigger }) => { [](#%5F%5Fcodelineno-6-80) console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`); [](#%5F%5Fcodelineno-6-81) }); [](#%5F%5Fcodelineno-6-82) await Vault.addListener('unlock', ({ vaultId }) => { [](#%5F%5Fcodelineno-6-83) console.log(`Vault ${vaultId} unlocked.`); [](#%5F%5Fcodelineno-6-84) }); [](#%5F%5Fcodelineno-6-85)}; [](#%5F%5Fcodelineno-6-86) [](#%5F%5Fcodelineno-6-87)// Permanently destroy the vault. [](#%5F%5Fcodelineno-6-88)const destroy = async () => { [](#%5F%5Fcodelineno-6-89) await Vault.destroy(); [](#%5F%5Fcodelineno-6-90)}; `` ## 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-7-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-8-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-9-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-10-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-11-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-12-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-13-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-14-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-15-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-16-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-17-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-18-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-19-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-20-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-21-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-22-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-23-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/plugins/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/plugins/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: `[](#%5F%5Fcodelineno-24-1)npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration ` Then use the following prompt: `` [](#%5F%5Fcodelineno-25-1)Use the `ionic-enterprise-sdk-migration` skill from `capawesome-team/skills` to migrate my project from Ionic Identity Vault to `@capawesome-team/capacitor-vault`. `` Alternatively, if you want to perform the migration manually, you can follow the instructions in this 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. That map has the exact shape expected by this plugin's [importData(...)](#importdata) method, so the two can be bridged directly: `[](#%5F%5Fcodelineno-26-1)import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-26-2)// Your existing Identity Vault instance. [](#%5F%5Fcodelineno-26-3)import { vault as identityVault } from './identity-vault'; [](#%5F%5Fcodelineno-26-4) [](#%5F%5Fcodelineno-26-5)const MIGRATION_KEY = 'capacitor-vault-migrated'; [](#%5F%5Fcodelineno-26-6) [](#%5F%5Fcodelineno-26-7)const migrateFromIdentityVault = async () => { [](#%5F%5Fcodelineno-26-8) // Skip if the migration has already been performed. [](#%5F%5Fcodelineno-26-9) if (localStorage.getItem(MIGRATION_KEY)) { [](#%5F%5Fcodelineno-26-10) return; [](#%5F%5Fcodelineno-26-11) } [](#%5F%5Fcodelineno-26-12) // Nothing to migrate if the old vault is empty. [](#%5F%5Fcodelineno-26-13) if (await identityVault.isEmpty()) { [](#%5F%5Fcodelineno-26-14) localStorage.setItem(MIGRATION_KEY, 'true'); [](#%5F%5Fcodelineno-26-15) return; [](#%5F%5Fcodelineno-26-16) } [](#%5F%5Fcodelineno-26-17) [](#%5F%5Fcodelineno-26-18) // Unlocking prompts the user to authenticate (e.g. via biometrics). [](#%5F%5Fcodelineno-26-19) await identityVault.unlock(); [](#%5F%5Fcodelineno-26-20) const data = await identityVault.exportVault(); [](#%5F%5Fcodelineno-26-21) [](#%5F%5Fcodelineno-26-22) // Initialize the new vault and import the data. [](#%5F%5Fcodelineno-26-23) await Vault.initialize({ type: VaultType.Biometric }); [](#%5F%5Fcodelineno-26-24) await Vault.unlock(); [](#%5F%5Fcodelineno-26-25) await Vault.importData({ data }); [](#%5F%5Fcodelineno-26-26) [](#%5F%5Fcodelineno-26-27) // Clear the old vault and mark the migration as complete. [](#%5F%5Fcodelineno-26-28) await identityVault.clear(); [](#%5F%5Fcodelineno-26-29) localStorage.setItem(MIGRATION_KEY, 'true'); [](#%5F%5Fcodelineno-26-30)}; ` 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. **Note**: 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. ## 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). June 1, 2026 Back to top