Announcing the Capacitor Vault Plugin¶

Today we are excited to announce our brand new Capacitor Vault plugin. 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.

Capacitor Vault Demo on iOS

Why a Vault?¶

We already have the Capacitor Secure Preferences plugin for encrypted key/value storage and the Capacitor 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 popularized, and it is the one being discontinued 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 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.

Initialize the Vault¶

Before any other call, you initialize the vault once per session with initialize(...):

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() call triggers the platform's authentication prompt:

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(...) and getValue(...) behave like any key/value store:

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(), and subscribe to lock and unlock events to keep your UI in sync:

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:

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 — relational data with queries, joins, and indexes. Reach for it when the shape of your data calls for it.
Capacitor Secure Preferences plugin — 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 — 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 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(...) and 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.

For an AI-assisted migration, add the Capawesome Skills to your AI tool:

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. 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

Conclusion¶

We hope you are as excited as we are about the new Capacitor Vault plugin. 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 for the full surface area, and if you spot something missing, just open an issue on GitHub.

Related reading:

Stay in the loop:

Join the conversation on the Capawesome Discord server and subscribe to the Capawesome newsletter to stay updated on the latest news.