---
title: Exploring the Capacitor Secure Preferences API
description: "Practical guide to the Capacitor Secure Preferences API: store tokens, passwords, and secrets in Keychain and Android Keystore."
date:
  created: 2025-07-14 
  updated: 2026-07-17
authors:
  - ebarooni
categories:
  - Capacitor
  - Guides
  - SDKs
links:
  - Capacitor Secure Preferences: sdks/capacitor/secure-preferences.md
faq: true
---

# Exploring the Capacitor Secure Preferences API

Securing sensitive data in mobile applications is crucial for protecting user privacy and maintaining trust. With the [Capacitor Secure Preferences plugin](../../sdks/capacitor/secure-preferences.md) from Capawesome, developers can implement robust secure storage solutions in their Ionic and Capacitor applications, leveraging native security features like Android Keystore and iOS Keychain to protect sensitive information such as authentication tokens, passwords, and personal data through a unified API that ensures data remains encrypted and secure across all platforms.

<!-- more -->

## Installation

To install the Capacitor Secure Preferences plugin, please refer to the [Installation](../../sdks/capacitor/secure-preferences.md/#installation) section in the plugin documentation.

## Usage

Let's explore the key features of the Capacitor Secure Preferences API and how to implement them in your Ionic applications.

### Storing Values

The primary method of the Capacitor Secure Preferences API is to securely store sensitive data. Use the [`set(...)`](../../sdks/capacitor/secure-preferences.md#set) method to store key-value pairs:

```ts
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const set = async () => {
    await SecurePreferences.set({
        key: 'token',
        value: 'value'
    });
};
```

The plugin automatically handles encryption and storage using the most secure method available on each platform. On Android, data is encrypted using the Android Keystore, while on iOS, it's stored in the iOS Keychain.

### Retrieving Values

To retrieve stored data, use the [`get(...)`](../../sdks/capacitor/secure-preferences.md#get) method:

```ts
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const get = async () => {
    const { value } = await SecurePreferences.get({
        key: 'token',
    });
    console.log(value)
};
```

The `get(...)` method returns an object with a `value` property that contains the stored data, or `null` if no data exists for the specified key. Always handle the case where the requested key doesn't exist to prevent application errors.

### Retrieving Keys

To retrieve all keys stored in secure preferences, you can use the `keys()` method. This method returns an array of all keys currently stored, allowing you to manage them as needed.

```ts
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const keys = async () => {
    const { keys } = await SecurePreferences.keys();
    console.log(keys)   // ['token', 'password', ...]
};
```

Do not use this method to check if a specific key exists, as it returns all keys. Instead, use the `get(...)` method to check for the existence of a specific key and retrieve its value.

### Deleting Values

You can delete values from secure storage either one at a time or all at once, depending on your needs.

To remove a specific key-value pair, use the [`remove(...)`](../../sdks/capacitor/secure-preferences.md#remove) method:

```ts
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const remove = async () => {
    await SecurePreferences.remove({
      key: 'token',
    });
};
```

If you want to remove everything stored in secure preferences, you can use the `clear()` method. This method does not take any arguments and deletes all keys and values currently saved in secure storage. It’s useful for scenarios like logging out a user or resetting the app’s secure data.

```ts
import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';
    
const clear = async () => {
    await SecurePreferences.clear();
};
```

## Best Practices

When using Capacitor Secure Preferences plugin in your application, consider these best practices:

1. **Store only Sensitive Data**: Secure Preferences is meant to store sensitive or confidential information, such as tokens, passwords or personal identifiers. Avoid cluttering secure storage with large amounts of non-sensitive data.
2. **Handle Missing or Deleted Data**: Users might clear secure storage manually, reinstall the app or switch devices. Therefore, always check if a key exists before using its value and provide fallback flows if data is missing. A fallback flow can be re-prompting the user to log in or re-enter information.
3. **Never Hardcode Sensitive Data or Keys**: While Secure Preferences encrypts values (except for web platform), keys themselves are often stored as plain strings. Avoid giving away meaning in key names and never hardcode secrets or credentials directly into your app's source code. Instead, use generic key names that don't reveal the data's purpose.

## FAQ

### Is data actually encrypted when I test my app in a browser?

No. The web implementation stores values unencrypted in `localStorage`, purely to make cross-platform development easier — it's explicitly meant for development and testing only, and should never be relied on for production data. Real encryption, backed by the Android Keystore and iOS Keychain, only applies on Android and iOS.

### Should I use Secure Preferences or the Vault plugin for storing an auth token?

It depends on whether the app should be able to read the value without the user present. Secure Preferences is a transparent key/value store — encrypted at rest, but readable by your app at any time without prompting the user, which fits something like an OAuth refresh token the app needs in the background. If you need the stored value to require an active biometric or passcode unlock before your app can read it, that's what the [Capacitor Vault plugin](../../sdks/capacitor/vault.md) is for instead.

### Can I use `keys()` to check if a specific value like a token exists?

Not efficiently, and it's explicitly discouraged. `keys()` returns every key currently stored, not a targeted existence check — use `get(...)` for a specific key instead, and treat a `null` result as "doesn't exist," rather than fetching the full key list and searching it yourself.

### What happens to stored values if the user reinstalls the app or gets a new phone?

They're gone, and your app needs to handle that gracefully. A fresh install has no access to previously stored secure data — on Android, the Keystore encryption key doesn't survive an uninstall, and on iOS, Keychain items aren't synced via iCloud (though they can appear in encrypted local backups restored onto the same device). Always design a fallback flow, like re-prompting for login, rather than assuming stored values persist indefinitely.

### If I need to store structured or relational data securely, should I use Secure Preferences?

No — it's designed for small key/value pairs, not structured records. For anything that needs queries, joins, or larger datasets — an offline-first app syncing structured records, for example — the [Capacitor SQLite plugin](../../sdks/capacitor/sqlite.md) with SQLCipher-based encryption is the better fit.

## Related Posts

- [Alternative to the Ionic Identity Vault Plugin](./alternative-to-ionic-identity-vault-plugin.md)
- [Alternative to the Ionic Secure Storage Plugin](./alternative-to-ionic-secure-storage-plugin.md)
- [Announcing the Biometrics Plugin for Capacitor](./announcing-the-capacitor-biometrics-plugin.md)
- [Announcing the Secure Preferences Plugin for Capacitor](./announcing-the-capacitor-secure-preferences-plugin.md)

## Conclusion

The Capacitor Secure Preferences plugin provides a simple yet powerful way to protect sensitive data in your Ionic and Capacitor applications. By following best practices and leveraging platform-native security features, you can keep user data safe and maintain trust in your apps.

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/){:target="_blank"} and follow us on [X (formerly Twitter)](https://x.com/capawesomeio){:target="_blank"}.

If you have any questions or need assistance with the Capacitor Secure Preferences Plugin, feel free to reach out to the Capawesome team. We're here to help you implement secure biometric authentication in your Ionic applications.