--- title: Announcing the Capacitor Vault Plugin description: The new Capacitor Vault plugin stores secrets behind biometrics or a device passcode — a non-enterprise alternative to Ionic Identity Vault. date: created: 2026-06-01 updated: 2026-07-10 authors: - robingenz categories: - Announcements - Capacitor - SDKs links: - Capacitor Vault: sdks/capacitor/vault.md faq: true --- # Capacitor Vault Plugin: Store Secrets Securely Today we're introducing the [Capacitor Vault plugin](../../sdks/capacitor/vault.md). 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](../../insiders/index.md).
Capacitor Vault Demo on iOS
## Why a Vault We already have the [Capacitor Secure Preferences plugin](../../sdks/capacitor/secure-preferences.md) for encrypted key/value storage and the [Capacitor Biometrics plugin](../../sdks/capacitor/biometrics.md) 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){:target="_blank"} popularized, and it is the one being [discontinued](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products){:target="_blank"} 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 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 To install the Capacitor Vault plugin, please refer to the [Installation](../../sdks/capacitor/vault.md/#installation) section in the plugin documentation. ## A Quick Tour Let's walk through the core flow: initialize, unlock, read and write, lock. You can find the full API in the [API Reference](../../sdks/capacitor/vault.md#api). ### Initialize the Vault Before any other call, you initialize the vault once per session with [`initialize(...)`](../../sdks/capacitor/vault.md#initialize): ```typescript import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; const initialize = async () => { await Vault.initialize({ type: VaultType.Biometric, title: 'Unlock vault', cancelButtonText: 'Cancel', iosFallbackButtonText: 'Use Passcode', lockAfterBackgrounded: 30000, // Use 0 to lock immediately on background }); }; ``` 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 Once initialized, an [`unlock()`](../../sdks/capacitor/vault.md#unlock) call triggers the platform's authentication prompt: ```typescript import { Vault, ErrorCode } from '@capawesome-team/capacitor-vault'; const unlock = async () => { try { await Vault.unlock(); } catch (error) { if (error.code === ErrorCode.UnlockCanceled) { // User dismissed the prompt } else if (error.code === ErrorCode.KeyInvalidated) { // Biometric set changed — re-enrollment required } else { throw error; } } }; ``` 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 While the vault is unlocked, [`setValue(...)`](../../sdks/capacitor/vault.md#setvalue) and [`getValue(...)`](../../sdks/capacitor/vault.md#getvalue) behave like any key/value store: ```typescript import { Vault } from '@capawesome-team/capacitor-vault'; const storeAndRead = async () => { await Vault.setValue({ key: 'session_token', value: 'eyJhbGciOiJIUzI1NiIs...' }); const { value } = await Vault.getValue({ key: 'session_token' }); return value; }; ``` 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 manually with [`lock()`](../../sdks/capacitor/vault.md#lock), and subscribe to lock and unlock events to keep your UI in sync: ```typescript import { Vault } from '@capawesome-team/capacitor-vault'; const setup = async () => { await Vault.addListener('lock', ({ vaultId, trigger }) => { console.log(`Vault ${vaultId} locked (trigger: ${trigger}).`); }); await Vault.addListener('unlock', ({ vaultId }) => { console.log(`Vault ${vaultId} unlocked.`); }); }; ``` 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 Every method accepts an optional `vaultId`. Pass different identifiers and you get fully independent vaults — separate keys, separate lock state, separate prompts: ```typescript import { Vault, VaultType } from '@capawesome-team/capacitor-vault'; const initializeBoth = async () => { await Vault.initialize({ vaultId: 'alice', type: VaultType.Biometric, title: 'Unlock Alice\'s vault', }); await Vault.initialize({ vaultId: 'bob', type: VaultType.BiometricOrDevicePasscode, title: 'Unlock Bob\'s vault', lockAfterBackgrounded: 60000, }); }; ``` 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 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](../../sdks/capacitor/sqlite.md)** — relational data with queries, joins, and indexes. Reach for it when the shape of your data calls for it. - **[Capacitor Secure Preferences plugin](../../sdks/capacitor/secure-preferences.md)** — 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](../../sdks/capacitor/vault.md)** — 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 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){:target="_blank"} to see the plugin in action. ## Bonus: Video Walkthrough 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 If you're moving off Ionic Identity Vault, the [`exportData(...)`](../../sdks/capacitor/vault.md#exportdata) and [`importData(...)`](../../sdks/capacitor/vault.md#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](./alternative-to-ionic-identity-vault-plugin.md). For an AI-assisted migration, add the [Capawesome Skills](https://github.com/capawesome-team/skills){:target="_blank"} to your AI tool: ```bash 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 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/){ .md-button .md-button--primary } ## FAQ ### Which platforms does the Capacitor Vault plugin support? The plugin supports Android, iOS, and the Web, and requires Capacitor 8 or later. The web implementation is `localStorage`-backed for cross-platform development and is not safe for production. ### How is the Vault plugin different from Secure Preferences? The [Capacitor Secure Preferences plugin](../../sdks/capacitor/secure-preferences.md) is silent — the app reads values in the background with no user-facing gate. The Vault plugin adds an active lock: the user unlocks it once with biometrics or a passcode, and that session stays unlocked across many reads and writes until it locks again. ### Can I run more than one vault in the same app? Yes. Every method accepts an optional `vaultId`, so you can create fully independent vaults with their own keys, lock state, and prompts — for example, one per user account. ### Can I migrate from Ionic Identity Vault? Yes. The `exportData(...)` and `importData(...)` methods give you a one-shot migration path. See the [Ionic Identity Vault alternative](./alternative-to-ionic-identity-vault-plugin.md) post for the full API mapping. ## Conclusion With biometric and passcode unlock, multi-vault support, auto-lock, and hardware-backed encryption, the [Capacitor Vault plugin](../../sdks/capacitor/vault.md) 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](../../sdks/capacitor/vault.md#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){:target="_blank"} on GitHub. **Related reading:** - [Alternative to the Ionic Identity Vault Plugin](./alternative-to-ionic-identity-vault-plugin.md) - [Announcing the Capacitor Secure Preferences Plugin](./announcing-the-capacitor-secure-preferences-plugin.md) - [Announcing the Capacitor Biometrics Plugin](./announcing-the-capacitor-biometrics-plugin.md) - [Capacitor Privacy Screen: Hide Sensitive App Content](./capacitor-privacy-screen-hide-app-content.md) **Stay in the loop:** Join the conversation on the [Capawesome Discord server](https://discord.gg/VCXxSVjefW){:target="_blank"} and subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/){:target="_blank"} to stay updated on the latest news.