---
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/) 

* [  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 ](/docs/plugins/vault/)
* [  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

* [  Multiple Vaults ](#multiple-vaults)
* [  Vault, Secure Preferences, or SQLite? ](#vault-secure-preferences-or-sqlite)
* [  Demo App ](#demo-app)
* [  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/plugins/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 [Secure Preferences](/docs/plugins/secure-preferences/) plugin for encrypted key/value storage and the [Biometrics](/docs/plugins/biometrics/) plugin 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/plugins/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/plugins/vault/#api).

### Initialize the Vault[¶](#initialize-the-vault "Permanent link")

Before any other call, you initialize the vault once per session with [initialize(...)](/docs/plugins/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/plugins/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/plugins/vault/#setvalue) and [getValue(...)](/docs/plugins/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/plugins/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:

* **[SQLite](/docs/plugins/sqlite/)** — relational data with queries, joins, and indexes. Reach for it when the shape of your data calls for it.
* **[Secure Preferences](/docs/plugins/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.
* **[Vault](/docs/plugins/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.

## Migrating from Ionic Identity Vault[¶](#migrating-from-ionic-identity-vault "Permanent link")

If you're moving off Ionic Identity Vault, the [exportData(...)](/docs/plugins/vault/#exportdata) and [importData(...)](/docs/plugins/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/plugins/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/plugins/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 1, 2026 

 Back to top