--- description: Capacitor plugin to securely store and retrieve sensitive data like passwords and tokens using native secure storage mechanisms. title: Capacitor Secure Preferences Plugin - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/secure-preferences.png --- [ Skip to content](#capawesome-teamcapacitor-secure-preferences) [ 🔐 Introducing the **Capacitor Vault** plugin — store secrets behind biometrics or a device passcode.](/blog/announcing-the-capacitor-vault-plugin/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * Secure Preferences [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ FAQ ](#faq) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm or Yarn ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Web ](#web) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ FAQ ](#faq) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # @capawesome-team/capacitor-secure-preferences[¶](#capawesome-teamcapacitor-secure-preferences "Permanent link") Capacitor plugin to securely store key/value pairs such as passwords, tokens or other sensitive information. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[¶](#features "Permanent link") We are proud to offer one of the most complete and feature-rich Capacitor plugins for secure storage. Here are some of the key features: * 🖥️ **Cross-platform**: Native secure storage on Android and iOS, with a `localStorage`\-backed web implementation for development. * 🔒 **Secure**: Store sensitive information such as passwords securely using the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and [iOS Keychain](https://developer.apple.com/documentation/security/keychain-services). * 🔍 **Detailed Error Messages**: Get actionable error messages with specific failure reasons and error codes on iOS, making debugging keychain issues straightforward. * 🤝 **Compatibility**: Compatible with the [Biometrics](https://capawesome.io/docs/plugins/biometrics/), [SQLite](https://capawesome.io/docs/plugins/sqlite/), and [Vault](https://capawesome.io/docs/plugins/vault/) plugins. * 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * 🔁 **Up-to-date**: Always supports the latest Capacitor version. * ⭐️ **Support**: Priority support from the Capawesome Team. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Newsletter[¶](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Compatibility[¶](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.2.x | \>=8.x.x | Active support | ## Guides[¶](#guides "Permanent link") * [Alternative to the Ionic Secure Storage plugin](https://capawesome.io/blog/alternative-to-ionic-secure-storage-plugin/) * [Announcing the Capacitor Secure Preferences Plugin](https://capawesome.io/blog/announcing-the-capacitor-secure-preferences-plugin/) * [Exploring the Capacitor Secure Preferences API](https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/) * [How to Securely Store Credentials with Capacitor](https://capawesome.io/blog/how-to-securely-store-credentials-with-capacitor/) ## Installation[¶](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-secure-preferences` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-secure-preferences [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[¶](#android "Permanent link") #### Proguard[¶](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-4-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` ### Web[¶](#web "Permanent link") **Attention**: The web implementation uses `localStorage` to make cross-platform development easier. It is intended for development and testing purposes only and should NOT be used in production. ## Configuration[¶](#configuration "Permanent link") No configuration required for this plugin. ## Usage[¶](#usage "Permanent link") `[](#%5F%5Fcodelineno-5-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const clear = async () => { [](#%5F%5Fcodelineno-5-4) await SecurePreferences.clear(); [](#%5F%5Fcodelineno-5-5)}; [](#%5F%5Fcodelineno-5-6) [](#%5F%5Fcodelineno-5-7)const get = async () => { [](#%5F%5Fcodelineno-5-8) const { value } = await SecurePreferences.get({ [](#%5F%5Fcodelineno-5-9) key: 'password', [](#%5F%5Fcodelineno-5-10) }); [](#%5F%5Fcodelineno-5-11) console.log(value); [](#%5F%5Fcodelineno-5-12)}; [](#%5F%5Fcodelineno-5-13) [](#%5F%5Fcodelineno-5-14)const keys = async () => { [](#%5F%5Fcodelineno-5-15) const { keys } = await SecurePreferences.keys(); [](#%5F%5Fcodelineno-5-16) console.log(keys); [](#%5F%5Fcodelineno-5-17)}; [](#%5F%5Fcodelineno-5-18) [](#%5F%5Fcodelineno-5-19)const remove = async () => { [](#%5F%5Fcodelineno-5-20) await SecurePreferences.remove({ [](#%5F%5Fcodelineno-5-21) key: 'password', [](#%5F%5Fcodelineno-5-22) }); [](#%5F%5Fcodelineno-5-23)}; [](#%5F%5Fcodelineno-5-24) [](#%5F%5Fcodelineno-5-25)const set = async () => { [](#%5F%5Fcodelineno-5-26) await SecurePreferences.set({ [](#%5F%5Fcodelineno-5-27) key: 'password', [](#%5F%5Fcodelineno-5-28) value: '123456', [](#%5F%5Fcodelineno-5-29) }); [](#%5F%5Fcodelineno-5-30)}; ` ## API[¶](#api "Permanent link") * [clear()](#clear) * [get(...)](#get) * [keys()](#keys) * [remove(...)](#remove) * [set(...)](#set) * [Interfaces](#interfaces) ### clear()[¶](#clear "Permanent link") `[](#%5F%5Fcodelineno-6-1)clear() => Promise ` Clear all stored keys and values. **Since:** 7.0.0 --- ### get(...)[¶](#get "Permanent link") `[](#%5F%5Fcodelineno-7-1)get(options: GetOptions) => Promise ` Get the value associated with a key. | Param | Type | | ----------- | ------------------------- | | **options** | [GetOptions](#getoptions) | **Returns:** `Promise<[GetResult](#getresult)>` **Since:** 7.0.0 --- ### keys()[¶](#keys "Permanent link") `[](#%5F%5Fcodelineno-8-1)keys() => Promise ` Get a list of all stored keys. **Returns:** `Promise<[KeysResult](#keysresult)>` **Since:** 7.0.0 --- ### remove(...)[¶](#remove "Permanent link") `[](#%5F%5Fcodelineno-9-1)remove(options: RemoveOptions) => Promise ` Remove a value given its key. | Param | Type | | ----------- | ------------------------------- | | **options** | [RemoveOptions](#removeoptions) | **Since:** 7.0.0 --- ### set(...)[¶](#set "Permanent link") `[](#%5F%5Fcodelineno-10-1)set(options: SetOptions) => Promise ` Set a value given its key. On **Web**, the value is stored unencrypted in `localStorage`. This is for development purposes only and should NOT be used in production. | Param | Type | | ----------- | ------------------------- | | **options** | [SetOptions](#setoptions) | **Since:** 7.0.0 --- ### Interfaces[¶](#interfaces "Permanent link") #### GetResult[¶](#getresult "Permanent link") | Prop | Type | Description | Since | | --------- | -------------- | -------------------- | ----- | | **value** | string \| null | The retrieved value. | 7.0.0 | #### GetOptions[¶](#getoptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ----------------------------------------- | ----- | | **key** | string | The key associated with the stored value. | 7.0.0 | #### KeysResult[¶](#keysresult "Permanent link") | Prop | Type | Description | Since | | -------- | ---------- | -------------------------- | ----- | | **keys** | string\[\] | The available stored keys. | 7.0.0 | #### RemoveOptions[¶](#removeoptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ------------------ | ----- | | **key** | string | The key to remove. | 7.0.0 | #### SetOptions[¶](#setoptions "Permanent link") | Prop | Type | Description | Since | | --------- | ------ | ----------------------------------------- | ----- | | **key** | string | The key associated with the stored value. | 7.0.0 | | **value** | string | The value to store. | 7.0.0 | ## FAQ[¶](#faq "Permanent link") ### Where is the data stored?[¶](#where-is-the-data-stored "Permanent link") On Android, the encryption key is stored in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore) and the encrypted values are stored in a `SharedPreferences` file (`CAPAWESOME_SECURE_PREFERENCES.xml`). On iOS, the encrypted values are stored as [Keychain](https://developer.apple.com/documentation/security/keychain-services) items. On Android, the encryption key in the Keystore is never backed up. The encrypted values in `SharedPreferences` are part of [Android Auto Backup](https://developer.android.com/identity/data/autobackup) by default, but the backed-up ciphertext is unusable on another device without the Keystore key; to exclude the preferences file (`CAPAWESOME_SECURE_PREFERENCES.xml`) from backup, see the [Android documentation](https://developer.android.com/identity/data/autobackup#IncludingFiles). On iOS, the Keychain items are not synced to iCloud, but they may be included in encrypted local device backups and restored on a new device. ### When should I use Secure Preferences instead of Vault or SQLite?[¶](#when-should-i-use-secure-preferences-instead-of-vault-or-sqlite "Permanent link") All three plugins protect data on the device, but they target different problems: * **Secure Preferences** (this plugin) is a transparent key/value store. Values are encrypted at rest using the Android Keystore and iOS Keychain, but the app can read them at any time without prompting the user. Reach for it when you need to keep small bits of sensitive data around that the app itself accesses in the background — typical examples are OAuth refresh tokens, server-issued API keys, or preference flags that contain personal information. * **[Vault](https://capawesome.io/docs/plugins/vault/)** is a key/value store with an active lock state and biometric or device-passcode gating. The user has to unlock it before any read or write, and it locks again on demand or after a configurable background timeout. Reach for it when access to the data should require an explicit user action — a password manager's entries, an authenticator app's TOTP secrets, or the credentials sitting behind an "app lock" screen. * **[SQLite](https://capawesome.io/docs/plugins/sqlite/)** is a full relational database with optional SQLCipher encryption. Use it when the shape of your data calls for queries, joins, indexes, or large record sets — for example, an offline-first app that syncs structured records, or anything you would otherwise model with a server-side database. A quick decision tree: * Need encrypted key/value storage the app can read freely in the background? → **Secure Preferences**. * Need encrypted key/value storage the user must actively unlock with biometrics or a passcode? → **Vault**. * Need queries, relations, or large datasets? → **SQLite**. The three plugins are designed to coexist. A real-world app might use Secure Preferences for app-managed tokens, SQLite for synced records, and Vault for the master password that protects everything else. ## Changelog[¶](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/CHANGELOG.md). ## Breaking Changes[¶](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/BREAKING.md). ## License[¶](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/secure-preferences/LICENSE). May 21, 2026 Back to top