--- description: Practical guide to the Capacitor Secure Preferences API: store tokens, passwords, and secrets in Keychain and Android Keystore. title: Exploring the Capacitor Secure Preferences API - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/exploring-the-capacitor-secure-preferences-api.png --- [Skip to content ](#exploring-the-capacitor-secure-preferences-api) [🖥️ Introducing the **Capacitor Electron Platform** — build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ 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/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ 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/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ 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, Yarn, or bun ](/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 * [ Best Practices ](#best-practices) * [ FAQ ](#faq) * [ Related Posts ](#related-posts) * [ Conclusion ](#conclusion) * Related links # Exploring the Capacitor Secure Preferences API[¶](#exploring-the-capacitor-secure-preferences-api "Permanent link") Securing sensitive data in mobile applications is crucial for protecting user privacy and maintaining trust. With the [Capacitor Secure Preferences plugin](/docs/sdks/capacitor/secure-preferences/) 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. ## Installation[¶](#installation "Permanent link") To install the Capacitor Secure Preferences plugin, please refer to the [Installation](/docs/sdks/capacitor/secure-preferences/#installation) section in the plugin documentation. ## Usage[¶](#usage "Permanent link") Let's explore the key features of the Capacitor Secure Preferences API and how to implement them in your Ionic applications. ### Storing Values[¶](#storing-values "Permanent link") The primary method of the Capacitor Secure Preferences API is to securely store sensitive data. Use the [set(...)](/docs/sdks/capacitor/secure-preferences/#set) method to store key-value pairs: `[](#%5F%5Fcodelineno-0-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-0-2) [](#%5F%5Fcodelineno-0-3)const set = async () => { [](#%5F%5Fcodelineno-0-4) await SecurePreferences.set({ [](#%5F%5Fcodelineno-0-5) key: 'token', [](#%5F%5Fcodelineno-0-6) value: 'value' [](#%5F%5Fcodelineno-0-7) }); [](#%5F%5Fcodelineno-0-8)}; ` 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[¶](#retrieving-values "Permanent link") To retrieve stored data, use the [get(...)](/docs/sdks/capacitor/secure-preferences/#get) method: `[](#%5F%5Fcodelineno-1-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-1-2) [](#%5F%5Fcodelineno-1-3)const get = async () => { [](#%5F%5Fcodelineno-1-4) const { value } = await SecurePreferences.get({ [](#%5F%5Fcodelineno-1-5) key: 'token', [](#%5F%5Fcodelineno-1-6) }); [](#%5F%5Fcodelineno-1-7) console.log(value) [](#%5F%5Fcodelineno-1-8)}; ` 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[¶](#retrieving-keys "Permanent link") 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. `[](#%5F%5Fcodelineno-2-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-2-2) [](#%5F%5Fcodelineno-2-3)const keys = async () => { [](#%5F%5Fcodelineno-2-4) const { keys } = await SecurePreferences.keys(); [](#%5F%5Fcodelineno-2-5) console.log(keys) // ['token', 'password', ...] [](#%5F%5Fcodelineno-2-6)}; ` 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[¶](#deleting-values "Permanent link") 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(...)](/docs/sdks/capacitor/secure-preferences/#remove) method: `[](#%5F%5Fcodelineno-3-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3)const remove = async () => { [](#%5F%5Fcodelineno-3-4) await SecurePreferences.remove({ [](#%5F%5Fcodelineno-3-5) key: 'token', [](#%5F%5Fcodelineno-3-6) }); [](#%5F%5Fcodelineno-3-7)}; ` 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. `[](#%5F%5Fcodelineno-4-1)import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences'; [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)const clear = async () => { [](#%5F%5Fcodelineno-4-4) await SecurePreferences.clear(); [](#%5F%5Fcodelineno-4-5)}; ` ## Best Practices[¶](#best-practices "Permanent link") 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[¶](#faq "Permanent link") ### Is data actually encrypted when I test my app in a browser?[¶](#is-data-actually-encrypted-when-i-test-my-app-in-a-browser "Permanent link") 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?[¶](#should-i-use-secure-preferences-or-the-vault-plugin-for-storing-an-auth-token "Permanent link") 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](/docs/sdks/capacitor/vault/) is for instead. ### Can I use `keys()` to check if a specific value like a token exists?[¶](#can-i-use-keys-to-check-if-a-specific-value-like-a-token-exists "Permanent link") 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?[¶](#what-happens-to-stored-values-if-the-user-reinstalls-the-app-or-gets-a-new-phone "Permanent link") 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?[¶](#if-i-need-to-store-structured-or-relational-data-securely-should-i-use-secure-preferences "Permanent link") 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](/docs/sdks/capacitor/sqlite/) with SQLCipher-based encryption is the better fit. ## Related Posts[¶](#related-posts "Permanent link") * [Alternative to the Ionic Identity Vault Plugin](/blog/alternative-to-ionic-identity-vault-plugin/) * [Alternative to the Ionic Secure Storage Plugin](/blog/alternative-to-ionic-secure-storage-plugin/) * [Announcing the Biometrics Plugin for Capacitor](/blog/announcing-the-capacitor-biometrics-plugin/) * [Announcing the Secure Preferences Plugin for Capacitor](/blog/announcing-the-capacitor-secure-preferences-plugin/) ## Conclusion[¶](#conclusion "Permanent link") 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/) and follow us on [X (formerly Twitter)](https://x.com/capawesomeio). 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. July 17, 2026 Back to top ```json { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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.", "image": "https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png", "datePublished": "2025-07-14T00:00:00+00:00", "dateModified": "2026-07-17T00:00:00+00:00", "author": [ { "@type": "Person", "name": "Ehsan Barooni", "url": "https://github.com/ebarooni" } ], "publisher": { "@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": { "@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg" } }, "articleSection": "Capacitor", "keywords": ["Capacitor", "Guides", "SDKs"], "isPartOf": { "@type": "Blog", "@id": "https://capawesome.io/blog/#blog" }, "mainEntityOfPage": "https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/", "url": "https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://capawesome.io/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://capawesome.io/blog/" }, { "@type": "ListItem", "position": 3, "name": "Exploring the Capacitor Secure Preferences API", "item": "https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/" } ] } {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Is data actually encrypted when I test my app in a browser?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Should I use Secure Preferences or the Vault plugin for storing an auth token?", "acceptedAnswer": {"@type": "Answer", "text": "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 is for instead."}}, {"@type": "Question", "name": "Can I use keys() to check if a specific value like a token exists?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "What happens to stored values if the user reinstalls the app or gets a new phone?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "If I need to store structured or relational data securely, should I use Secure Preferences?", "acceptedAnswer": {"@type": "Answer", "text": "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 with SQLCipher-based encryption is the better fit."}}], "url": "https://capawesome.io/blog/exploring-the-capacitor-secure-preferences-api/"} ```