---
title: Alternative to the Ionic Identity Vault Plugin
description: Migrate from Ionic Identity Vault to the Capacitor Vault plugin — a near drop-in replacement with biometric unlock, auto-lock, and multi-vault support.
date:
  created: 2026-02-09
  updated: 2026-07-17
authors:
  - robingenz
categories:
  - Capacitor
  - Guides
  - SDKs
links:
  - Capacitor Vault: sdks/capacitor/vault.md
faq: true
---

# Alternative to the Ionic Identity Vault Plugin

Looking for a way to protect sensitive data and authenticate users in your Capacitor app? With [Ionic discontinuing](https://ionic.io/blog/important-announcement-the-future-of-ionics-commercial-products){:target="_blank"} their commercial Identity Vault plugin, developers need a reliable alternative for **biometric authentication** (Face ID, fingerprint) and secure session management. The [Capacitor Vault plugin](../../sdks/capacitor/vault.md) from Capawesome is a near drop-in replacement — same active lock pattern, the same method names for the core operations, multi-vault support out of the box, and no enterprise subscription required.

For background on the plugin, see our [announcement post](./announcing-the-capacitor-vault-plugin.md).

<!-- more -->

<div class="capawesome-z29o10a">
  <a href="/" target="_blank">
    <img alt="Build and deploy your Capacitor app with Capawesome Cloud" src="https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1" />
  </a>
</div>

## Key Takeaways

- The [Capacitor Vault plugin](../../sdks/capacitor/vault.md) is a near drop-in replacement for Ionic Identity Vault — no enterprise subscription required.
- Core operations (`unlock`, `lock`, `setValue`, `getValue`, `removeValue`, `clear`) keep the same method names; most calls switch from positional arguments to an options object.
- The constructor `new Vault(config)` becomes a single static `initialize(...)` call, and `type` + `deviceSecurityType` collapse into one `VaultType` enum.
- Multi-vault support is built in via the `vaultId` option on every method.
- Stored data can't be copied across directly — migrate it at runtime while both plugins are installed, using Identity Vault's `exportVault()` and the Capacitor Vault plugin's `importData(...)`.

## Introduction

Ionic Identity Vault combined biometric authentication, encrypted storage, and session management into a single plugin. It let developers store tokens and credentials securely, lock and unlock a vault with Face ID or fingerprint, and automatically clear sensitive data after inactivity. Following Ionic's decision to phase out their commercial products, teams need a replacement.

The [Capacitor Vault plugin](../../sdks/capacitor/vault.md) from Capawesome was built for exactly this scenario. It covers the same surface — biometric or device-passcode unlock, a session-based lock model with auto-lock, hardware-backed key/value storage, and migration utilities — under an API that mirrors Identity Vault's most common methods. In most cases, migrating is a matter of swapping the import and adding a one-time `initialize(...)` call.

## Feature Comparison

Here's a side-by-side look at how Identity Vault features map to the Capacitor Vault plugin:

| Feature                    | Identity Vault                  | Capacitor Vault                                                                                                            |
| -------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Initialize vault           | `new Vault(config)`             | [`Vault.initialize(...)`](../../sdks/capacitor/vault.md#initialize)                                                        |
| Biometric unlock           | `Vault.unlock()`                | [`Vault.unlock()`](../../sdks/capacitor/vault.md#unlock)                                                                   |
| Lock vault                 | `Vault.lock()`                  | [`Vault.lock()`](../../sdks/capacitor/vault.md#lock)                                                                       |
| Check if locked            | `Vault.isLocked()`              | [`Vault.isLocked()`](../../sdks/capacitor/vault.md#islocked)                                                               |
| Store values               | `Vault.setValue(...)`           | [`Vault.setValue(...)`](../../sdks/capacitor/vault.md#setvalue)                                                            |
| Retrieve values            | `Vault.getValue(...)`           | [`Vault.getValue(...)`](../../sdks/capacitor/vault.md#getvalue)                                                            |
| Remove values              | `Vault.removeValue(...)`        | [`Vault.removeValue(...)`](../../sdks/capacitor/vault.md#removevalue)                                                      |
| List keys                  | `Vault.getKeys()`               | [`Vault.getKeys()`](../../sdks/capacitor/vault.md#getkeys)                                                                 |
| Clear all data             | `Vault.clear()`                 | [`Vault.clear()`](../../sdks/capacitor/vault.md#clear)                                                                     |
| Device credential fallback | `DeviceSecurityType.Both`       | `VaultType.BiometricOrDevicePasscode` / `VaultType.DevicePasscode`                                                         |
| Auto-lock on background    | `lockAfterBackgrounded`         | `lockAfterBackgrounded`                                                                                                    |
| Lock / unlock events       | `onLock` / `onUnlock` callbacks | [`addListener('lock', ...)`](../../sdks/capacitor/vault.md#addlistenerlock-)                                               |
| Multiple vaults            | Multiple `Vault` instances      | `vaultId` option on every method                                                                                           |
| Key invalidation           | Built-in                        | `invalidateOnBiometricEnrollment`                                                                                          |
| Export / import data       | Manual                          | [`exportData()`](../../sdks/capacitor/vault.md#exportdata) / [`importData(...)`](../../sdks/capacitor/vault.md#importdata) |
| Web fallback               | Built-in                        | `localStorage` (dev only)                                                                                                  |

Identity Vault's most common methods carry their names over to the Capacitor Vault plugin, so a typical migration touches the import statement, the constructor (now `initialize(...)`), and a few configuration option names.

!!! tip "AI-Assisted Migration"

    For a more guided experience, add the [Capawesome skills](https://github.com/capawesome-team/skills){:target="_blank"} to your project with `npx skills add capawesome-team/skills --skill ionic-enterprise-sdk-migration` and use the following prompt with your preferred AI coding assistant:

    ```
    Use the `ionic-enterprise-sdk-migration` skill from `capawesome-team/skills` to help me migrate from Ionic Identity Vault to the Capacitor Vault plugin.
    ```

## Migration from Identity Vault

Migrating from Identity Vault is largely a matter of swapping the constructor for an `initialize(...)` call and updating the import path. The following sections walk through the most common scenarios.

### Installation

Begin by removing the existing Identity Vault dependency and installing the Capacitor Vault plugin.
To install the [Capacitor Vault plugin](../../sdks/capacitor/vault.md), please refer to the [Installation](../../sdks/capacitor/vault.md#installation) section in the plugin documentation.

### Initializing the Vault

Identity Vault uses a `new Vault(config)` constructor for each vault instance. The Capacitor Vault plugin uses a static [`initialize(...)`](../../sdks/capacitor/vault.md#initialize) call that takes the same shape of configuration.

**Identity Vault:**

```typescript
import { Vault, DeviceSecurityType, VaultType } from '@ionic-enterprise/identity-vault';

const vault = new Vault({
  key: 'com.example.vault',
  type: VaultType.DeviceSecurity,
  deviceSecurityType: DeviceSecurityType.Both,
  lockAfterBackgrounded: 2000,
});
```

**Capacitor Vault:**

```typescript
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';

const initialize = async () => {
  await Vault.initialize({
    vaultId: 'com.example.vault',
    type: VaultType.BiometricOrDevicePasscode,
    lockAfterBackgrounded: 2000,
  });
};
```

Call `initialize(...)` once per session before any other method. The `vaultId` option corresponds to Identity Vault's `key`, and `type` collapses Identity Vault's separate `type` and `deviceSecurityType` into a single enum (`Biometric`, `BiometricOrDevicePasscode`, or `DevicePasscode`).

### Biometric Authentication

Identity Vault uses `vault.unlock()` to trigger biometric authentication. The Capacitor Vault plugin uses the same method name — only the import changes.

**Identity Vault:**

```typescript
const unlock = async () => {
  await vault.unlock();
};
```

**Capacitor Vault:**

```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 branch on the specific reason an unlock failed instead of catching a generic error. `UnlockCanceled` means the user dismissed the prompt; `KeyInvalidated` means the device's biometric set has changed and the vault needs to be reinitialized.

### Storing Values

Identity Vault's `setValue(...)` stores data inside the encrypted vault. The Capacitor Vault plugin uses the same method name with an options-object argument.

**Identity Vault:**

```typescript
const storeToken = async () => {
  await vault.setValue('session_token', 'eyJhbGciOiJIUzI1NiIs...');
};
```

**Capacitor Vault:**

```typescript
import { Vault } from '@capawesome-team/capacitor-vault';

const storeToken = async () => {
  await Vault.setValue({
    key: 'session_token',
    value: 'eyJhbGciOiJIUzI1NiIs...',
  });
};
```

### Retrieving Values

Reading a value follows the same pattern — positional arguments become an options object.

**Identity Vault:**

```typescript
const getToken = async () => {
  const token = await vault.getValue('session_token');
  return token;
};
```

**Capacitor Vault:**

```typescript
import { Vault } from '@capawesome-team/capacitor-vault';

const getToken = async () => {
  const { value } = await Vault.getValue({ key: 'session_token' });
  return value;
};
```

### Removing Values

Removing a single value uses the same `removeValue` method name in both plugins.

**Identity Vault:**

```typescript
const removeToken = async () => {
  await vault.removeValue('session_token');
};
```

**Capacitor Vault:**

```typescript
import { Vault } from '@capawesome-team/capacitor-vault';

const removeToken = async () => {
  await Vault.removeValue({ key: 'session_token' });
};
```

### Clearing All Data

`clear()` empties the vault while preserving its configuration.

**Identity Vault:**

```typescript
const clearVault = async () => {
  await vault.clear();
};
```

**Capacitor Vault:**

```typescript
import { Vault } from '@capawesome-team/capacitor-vault';

const clearAll = async () => {
  await Vault.clear();
};
```

### Session Management

Identity Vault's `lockAfterBackgrounded` option ports over directly to the Capacitor Vault plugin — set it during `initialize(...)` and the vault locks itself when the app has been backgrounded for that long. Lock and unlock callbacks are exposed as events:

```typescript
import { Vault } from '@capawesome-team/capacitor-vault';

const setupSessionHandling = async () => {
  await Vault.addListener('lock', ({ vaultId, trigger }) => {
    // trigger is 'MANUAL' or 'TIMEOUT'
    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

Identity Vault supports multiple vaults via multiple `Vault` instances. The Capacitor Vault plugin supports the same through the `vaultId` option, which every method accepts:

```typescript
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';

const initializeBoth = async () => {
  await Vault.initialize({
    vaultId: 'user-tokens',
    type: VaultType.Biometric,
  });
  await Vault.initialize({
    vaultId: 'app-settings',
    type: VaultType.BiometricOrDevicePasscode,
    lockAfterBackgrounded: 60000,
  });
};
```

Each vault keeps its own keys, lock state, and configuration — handy for multi-account apps or for separating data with different sensitivity levels.

### Migrating Stored Data

If your app already has data in an Identity Vault, you cannot move it across by reusing Identity Vault's keystore or keychain entries. The two plugins use incompatible storage formats — Identity Vault keeps the whole vault as a single encrypted blob (on Android partly via a closed-source dependency), while the Capacitor Vault plugin stores each value individually with its own encryption scheme. There is no way to decrypt Identity Vault's data without its proprietary implementation.

Instead, migrate the data at runtime while **both** plugins are still installed. Identity Vault's `exportVault()` returns a plain key/value map after the vault is unlocked, and that map has the exact shape the Capacitor Vault plugin's [`importData(...)`](../../sdks/capacitor/vault.md#importdata) method expects, so you can bridge the two directly:

```typescript
import { Vault, VaultType } from '@capawesome-team/capacitor-vault';
// Your existing Identity Vault instance.
import { vault as identityVault } from './identity-vault';

const MIGRATION_KEY = 'capacitor-vault-migrated';

const migrateFromIdentityVault = async () => {
  // Skip if the migration has already been performed.
  if (localStorage.getItem(MIGRATION_KEY)) {
    return;
  }
  // Nothing to migrate if the old vault is empty.
  if (await identityVault.isEmpty()) {
    localStorage.setItem(MIGRATION_KEY, 'true');
    return;
  }

  // Unlocking prompts the user to authenticate (e.g. via biometrics).
  await identityVault.unlock();
  const data = await identityVault.exportVault();

  // Initialize the new vault and import the data.
  await Vault.initialize({ type: VaultType.Biometric });
  await Vault.unlock();
  await Vault.importData({ data });

  // Clear the old vault and mark the migration as complete.
  await identityVault.clear();
  localStorage.setItem(MIGRATION_KEY, 'true');
};
```

Run this once before removing the Identity Vault dependency. The user has to authenticate a single time to unlock the old vault — this is unavoidable, since the data is protected by the device's biometric or passcode authentication by design. Once all users have migrated (for example, after a release cycle in which everyone has opened the app at least once), you can drop Identity Vault in a follow-up release.

## FAQ

### Is the Capacitor Vault plugin free, since it doesn't need an Ionic enterprise subscription?

It doesn't require Ionic Identity Vault's enterprise subscription, but it's still a paid plugin — part of [Capawesome Insiders](https://capawesome.io/insiders/){:target="_blank"}. The difference is licensing model, not price point: no per-seat enterprise contract, just a Capawesome Insiders subscription that covers this plugin alongside the rest of the catalog.

### What happens if a user's biometrics change after enrollment?

The Capacitor Vault plugin can invalidate the vault's key automatically when the device's enrolled biometrics change (fingerprint added/removed, new face enrolled) via the `invalidateOnBiometricEnrollment` option. When that happens, `unlock()` rejects with `ErrorCode.KeyInvalidated`, telling your app to prompt the user to reinitialize the vault rather than silently failing.

### Does the plugin support falling back to a device passcode if biometrics aren't available?

Yes, via `VaultType.BiometricOrDevicePasscode` — the same behavior as Identity Vault's `DeviceSecurityType.Both`. Use `VaultType.DevicePasscode` if you want to skip biometrics entirely and only accept the device passcode.

### Can I run multiple vaults with different lock timeouts in the same app?

Yes. Every method takes a `vaultId` option, so a multi-account app (or one that separates high-sensitivity data like payment tokens from lower-sensitivity settings) can initialize several vaults, each with its own `lockAfterBackgrounded` timeout and lock state.

### Can I migrate existing vault data without asking users to re-authenticate?

No — this one step is unavoidable. The old vault's contents are protected by the device's biometric or passcode authentication by design, so reading them via `exportVault()` requires unlocking the Identity Vault instance first. Users authenticate once during the migration, and everything after that uses the new vault normally.

## Need Help Migrating?

If you'd rather not handle the migration yourself, the Capawesome team can take care of it for you. Whether you're dealing with a straightforward swap or a more complex setup with custom session management, we offer dedicated migration services to get you up and running with minimal downtime and effort on your end.

[Book a Free Consultation](https://cal.com/team/capawesome/ionic-appflow-migration){ .md-button .md-button--primary }

## Conclusion

The discontinuation of Ionic Identity Vault doesn't have to disrupt your workflow. The [Capacitor Vault plugin](../../sdks/capacitor/vault.md) gives you a near drop-in replacement with the same active lock pattern, the same core method names, and first-class multi-vault support — without the enterprise subscription. For the full plugin documentation, see the [API Reference](../../sdks/capacitor/vault.md#api).

**Related reading:**

- [Announcing the Capacitor Vault Plugin](./announcing-the-capacitor-vault-plugin.md)
- [Alternatives to Ionic Enterprise Plugins](./alternatives-to-ionic-enterprise-plugins.md)
- [How to Securely Store Credentials with Capacitor](./how-to-securely-store-credentials-with-capacitor.md)

**Stay updated:**  

Have questions or want to share your migration experience? Join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW){:target="_blank"} to connect with the community. To stay updated with the latest updates, features, and news about Capawesome, Capacitor, and the Ionic ecosystem, subscribe to our [Capawesome newsletter](/newsletter/){:target="_blank"}.

**Need help migrating from Identity Vault?** [Contact us](mailto:support@capawesome.io) to get started.