--- description: The new Capacitor Vault plugin stores secrets behind biometrics or a device passcode — a non-enterprise alternative to Ionic Identity Vault. title: Announcing the Vault Plugin for Capacitor - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/announcing-the-capacitor-vault-plugin.png --- [Skip to content ](#announcing-the-capacitor-vault-plugin) [🔐 Introducing the **Capacitor Vault** plugin — store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/) * [ 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/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ 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/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ 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 * [ Multiple Vaults ](#multiple-vaults) * [ Vault, Secure Preferences, or SQLite? ](#vault-secure-preferences-or-sqlite) * [ Demo App ](#demo-app) * [ Bonus: Video Walkthrough ](#bonus-video-walkthrough) * [ Migrating from Ionic Identity Vault ](#migrating-from-ionic-identity-vault) * [ Get Started ](#get-started) * [ Conclusion ](#conclusion) * Related links # Announcing the Capacitor Vault Plugin[¶](#announcing-the-capacitor-vault-plugin "Permanent link") Today we are excited to announce our brand new [Capacitor Vault plugin](/docs/sdks/capacitor/vault/). It lets you store secrets behind an explicit biometric or device-passcode unlock — the foundation for password managers, authenticator apps, banking apps, and any app-lock screen. The plugin ships with multi-vault support, configurable auto-lock, hardware-backed encryption, and full cross-platform parity across Android, iOS, and Web. It is available now to all Capawesome [Insiders](/docs/insiders/). Capacitor Vault Demo on iOS ## Why a Vault?[¶](#why-a-vault "Permanent link") We already have the [Capacitor Secure Preferences plugin](/docs/sdks/capacitor/secure-preferences/) for encrypted key/value storage and the [Capacitor Biometrics plugin](/docs/sdks/capacitor/biometrics/) for on-demand biometric prompts. So why a new plugin? Because neither covers the "active lock + session" pattern. Secure Preferences is silent — the app reads values freely in the background, with no user-facing gate. Biometrics gives you a single prompt, but no notion of a session that stays unlocked across many reads and writes. That pattern is the one [Ionic Identity Vault](https://ionic.io/products/identity-vault) popularized, and it is the one being [discontinued](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products) alongside Ionic's other commercial products. The Capacitor Vault plugin fills that gap with a non-enterprise option — and adds first-class multi-vault support along the way. ## Highlights[¶](#highlights "Permanent link") Here is what you get out of the box: * **Active lock state.** A single biometric or passcode prompt unlocks the vault, so the app can read and write many values before locking again. * **Three vault types.** `Biometric`, `BiometricOrDevicePasscode`, and `DevicePasscode` — pick the authenticator that matches your threat model. * **Auto-lock on background.** Configure `lockAfterBackgrounded` and the vault locks itself when the app has been backgrounded for that long. * **Lock and unlock events.** A `lock` event with a `trigger` reason (`MANUAL` or `TIMEOUT`) and a matching `unlock` event make session state easy to reason about. * **Multi-vault.** Create independent vaults with their own keys, copy, and lock policies — for example, one per user account. * **Hardware-backed encryption.** Keys live in the Android Keystore and iOS Keychain, with AES-256-GCM as the data cipher. * **Key invalidation.** Detect when the device's biometric set changes and surface it as a typed `KEY_INVALIDATED` error so you can re-enroll the user. * **Export and import.** Built-in migration API for moving off Ionic Identity Vault or rotating storage. * **Typed error codes.** Conditions like `UNLOCK_CANCELED`, `KEY_INVALIDATED`, and `BIOMETRY_NOT_AVAILABLE` are distinct codes you can branch on. The plugin supports Capacitor 8 and above. A `localStorage`\-backed web implementation is included for cross-platform development, but is clearly marked unsafe for production. ## Installation[¶](#installation "Permanent link") To install the Capacitor Vault plugin, please refer to the [Installation](/docs/sdks/capacitor/vault/#installation) section in the plugin documentation. ## A Quick Tour[¶](#a-quick-tour "Permanent link") Let's walk through the core flow: initialize, unlock, read and write, lock. You can find the full API in the [API Reference](/docs/sdks/capacitor/vault/#api). ### Initialize the Vault[¶](#initialize-the-vault "Permanent link") Before any other call, you initialize the vault once per session with [initialize(...)](/docs/sdks/capacitor/vault/#initialize): `[](#%5F%5Fcodelineno-0-1)import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-0-2) [](#%5F%5Fcodelineno-0-3)const initialize = async () => { [](#%5F%5Fcodelineno-0-4) await Vault.initialize({ [](#%5F%5Fcodelineno-0-5) type: VaultType.Biometric, [](#%5F%5Fcodelineno-0-6) title: 'Unlock vault', [](#%5F%5Fcodelineno-0-7) cancelButtonText: 'Cancel', [](#%5F%5Fcodelineno-0-8) iosFallbackButtonText: 'Use Passcode', [](#%5F%5Fcodelineno-0-9) lockAfterBackgrounded: 30000, // Use 0 to lock immediately on background [](#%5F%5Fcodelineno-0-10) }); [](#%5F%5Fcodelineno-0-11)}; ` The `type` and `lockAfterBackgrounded` options shape the vault's behavior. Here we pick biometric-only authentication and ask the vault to lock itself after the app has been backgrounded for 30 seconds. ### Unlock the Vault[¶](#unlock-the-vault "Permanent link") Once initialized, an [unlock()](/docs/sdks/capacitor/vault/#unlock) call triggers the platform's authentication prompt: `[](#%5F%5Fcodelineno-1-1)import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-1-2) [](#%5F%5Fcodelineno-1-3)const unlock = async () => { [](#%5F%5Fcodelineno-1-4) try { [](#%5F%5Fcodelineno-1-5) await Vault.unlock(); [](#%5F%5Fcodelineno-1-6) } catch (error) { [](#%5F%5Fcodelineno-1-7) if (error.code === ErrorCode.UnlockCanceled) { [](#%5F%5Fcodelineno-1-8) // User dismissed the prompt [](#%5F%5Fcodelineno-1-9) } else if (error.code === ErrorCode.KeyInvalidated) { [](#%5F%5Fcodelineno-1-10) // Biometric set changed — re-enrollment required [](#%5F%5Fcodelineno-1-11) } else { [](#%5F%5Fcodelineno-1-12) throw error; [](#%5F%5Fcodelineno-1-13) } [](#%5F%5Fcodelineno-1-14) } [](#%5F%5Fcodelineno-1-15)}; ` Typed error codes let you react to the specific reason the unlock failed. A canceled prompt usually means the user changed their mind, while `KeyInvalidated` indicates the device's biometric set has changed and the vault must be destroyed and reinitialized. ### Read and Write Values[¶](#read-and-write-values "Permanent link") While the vault is unlocked, [setValue(...)](/docs/sdks/capacitor/vault/#setvalue) and [getValue(...)](/docs/sdks/capacitor/vault/#getvalue) behave like any key/value store: `[](#%5F%5Fcodelineno-2-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-2-2) [](#%5F%5Fcodelineno-2-3)const storeAndRead = async () => { [](#%5F%5Fcodelineno-2-4) await Vault.setValue({ key: 'session_token', value: 'eyJhbGciOiJIUzI1NiIs...' }); [](#%5F%5Fcodelineno-2-5) const { value } = await Vault.getValue({ key: 'session_token' }); [](#%5F%5Fcodelineno-2-6) return value; [](#%5F%5Fcodelineno-2-7)}; ` A single prompt covers the whole session, so you can perform as many reads and writes as you need without re-authenticating between them. ### Lock the Vault and Listen for Events[¶](#lock-the-vault-and-listen-for-events "Permanent link") Lock the vault manually with [lock()](/docs/sdks/capacitor/vault/#lock), and subscribe to lock and unlock events to keep your UI in sync: `` [](#%5F%5Fcodelineno-3-1)import { Vault } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3)const setup = async () => { [](#%5F%5Fcodelineno-3-4) await Vault.addListener('lock', ({ vaultId, trigger }) => { [](#%5F%5Fcodelineno-3-5) console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`); [](#%5F%5Fcodelineno-3-6) }); [](#%5F%5Fcodelineno-3-7) await Vault.addListener('unlock', ({ vaultId }) => { [](#%5F%5Fcodelineno-3-8) console.log(`Vault ${vaultId} unlocked.`); [](#%5F%5Fcodelineno-3-9) }); [](#%5F%5Fcodelineno-3-10)}; `` The `trigger` on the lock event tells you whether the vault was locked by an explicit `lock()` call (`MANUAL`) or by the auto-lock timer (`TIMEOUT`) — useful when the two cases warrant different UI feedback. ## Multiple Vaults[¶](#multiple-vaults "Permanent link") Every method accepts an optional `vaultId`. Pass different identifiers and you get fully independent vaults — separate keys, separate lock state, separate prompts: `[](#%5F%5Fcodelineno-4-1)import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)const initializeBoth = async () => { [](#%5F%5Fcodelineno-4-4) await Vault.initialize({ [](#%5F%5Fcodelineno-4-5) vaultId: 'alice', [](#%5F%5Fcodelineno-4-6) type: VaultType.Biometric, [](#%5F%5Fcodelineno-4-7) title: 'Unlock Alice\'s vault', [](#%5F%5Fcodelineno-4-8) }); [](#%5F%5Fcodelineno-4-9) await Vault.initialize({ [](#%5F%5Fcodelineno-4-10) vaultId: 'bob', [](#%5F%5Fcodelineno-4-11) type: VaultType.BiometricOrDevicePasscode, [](#%5F%5Fcodelineno-4-12) title: 'Unlock Bob\'s vault', [](#%5F%5Fcodelineno-4-13) lockAfterBackgrounded: 60000, [](#%5F%5Fcodelineno-4-14) }); [](#%5F%5Fcodelineno-4-15)}; ` This is handy for multi-account apps, where each user's secrets should live behind their own lock — or for apps that want to separate, say, an authenticator vault from a settings vault. ## Vault, Secure Preferences, or SQLite?[¶](#vault-secure-preferences-or-sqlite "Permanent link") We now ship three plugins that store data on the device, and the right choice depends on how the data is accessed: * **[Capacitor SQLite plugin](/docs/sdks/capacitor/sqlite/)** — relational data with queries, joins, and indexes. Reach for it when the shape of your data calls for it. * **[Capacitor Secure Preferences plugin](/docs/sdks/capacitor/secure-preferences/)** — encrypted key/value storage the app can read freely in the background. Good for OAuth refresh tokens, API keys, and server-issued credentials. * **[Capacitor Vault plugin](/docs/sdks/capacitor/vault/)** — encrypted key/value storage the user must actively unlock with biometrics or a passcode. Good for password manager entries, TOTP secrets, and anything behind an app-lock screen. The three plugins are designed to coexist. A real-world app might keep app-managed tokens in Secure Preferences, synced records in SQLite, and the master password that gates them in Vault. ## Demo App[¶](#demo-app "Permanent link") We built an open-source demo app that walks through the full flow — initialization, unlock, read and write, multi-vault, and lock handling. Have a look at the source on [GitHub](https://github.com/capawesome-team/capacitor-vault-demo) to see the plugin in action. ## Bonus: Video Walkthrough[¶](#bonus-video-walkthrough "Permanent link") Prefer to watch instead of read? We recorded a video walkthrough that takes you through the plugin step by step, from initialization to unlocking the vault and handling lock events. ## Migrating from Ionic Identity Vault[¶](#migrating-from-ionic-identity-vault "Permanent link") If you're moving off Ionic Identity Vault, the [exportData(...)](/docs/sdks/capacitor/vault/#exportdata) and [importData(...)](/docs/sdks/capacitor/vault/#importdata) methods give you a one-shot migration path. For a complete walkthrough of the API mapping, see our existing post on the [Ionic Identity Vault alternative](/blog/alternative-to-ionic-identity-vault-plugin/). For an AI-assisted migration, add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool: `[](#%5F%5Fcodelineno-5-1)npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration ` Then prompt your assistant to use the `ionic-enterprise-sdk-migration` skill to migrate from Ionic Identity Vault to `@capawesome-team/capacitor-vault`. ## Get Started[¶](#get-started "Permanent link") The Capacitor Vault plugin is available now to all Capawesome [Insiders](/insiders/). Becoming an Insider gets you access to this plugin, the rest of our Insiders-only Capacitor plugins, and priority support from the Capawesome team. [Become a Capawesome Insider](https://console.cloud.capawesome.io/) ## Conclusion[¶](#conclusion "Permanent link") We hope you are as excited as we are about the new [Capacitor Vault plugin](/docs/sdks/capacitor/vault/). With biometric and passcode unlock, multi-vault support, auto-lock, and hardware-backed encryption, it gives Capacitor developers a complete answer for storing secrets behind an active lock — and a non-enterprise alternative to Ionic Identity Vault. Be sure to check out the [API Reference](/docs/sdks/capacitor/vault/#api) for the full surface area, and if you spot something missing, just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues/new/choose) on GitHub. **Related reading:** * [Alternative to the Ionic Identity Vault Plugin](/blog/alternative-to-ionic-identity-vault-plugin/) * [Announcing the Capacitor Secure Preferences Plugin](/blog/announcing-the-capacitor-secure-preferences-plugin/) * [Announcing the Capacitor Biometrics Plugin](/blog/announcing-the-capacitor-biometrics-plugin/) **Stay in the loop:** Join the conversation on the [Capawesome Discord server](https://discord.gg/VCXxSVjefW) and subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter) to stay updated on the latest news. June 12, 2026 Back to top