Expo

SecureStore

expo-secure-store provides a way to encrypt and securely store key–value pairs locally on the device. Each Expo project has a separate storage system and has no access to the storage of other Expo projects. Please note that for iOS standalone apps, data stored with expo-secure-store can persist across app installs.
iOS: Values are stored using the keychain services as kSecClassGenericPassword. iOS has the additional option of being able to set the value's kSecAttrAccessible attribute, which controls when the value is available to be fetched.
Android: Values are stored in SharedPreferences, encrypted with Android's Keystore system.
Size limit for a value is 2048 bytes. An attempt to store larger values may fail. Currently, we print a warning when the limit is reached, but in a future SDK version, we may throw an error.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
  • This API is not compatible on devices running Android 5 or older.

Installation

expo install expo-secure-store

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

API

import * as SecureStore from 'expo-secure-store';

SecureStore.isAvailableAsync()

Returns whether the SecureStore API is enabled on the current device.

Returns

Async boolean, indicating whether the SecureStore API is available on the current device. Currently this resolves true on iOS and Android only.

SecureStore.setItemAsync(key, value, options)

Store a key–value pair.

Arguments

  • key (string) -- The key to associate with the stored value. Keys may contain alphanumeric characters ., -, and _.
  • value (string) -- The value to store. Size limit is 2048 bytes.
  • options (object) (optional) -- A map of options:
    • keychainService (string) --
      • iOS: The item's service, equivalent to kSecAttrService
      • Android: Equivalent of the public/private key pair Alias
      NOTE If the item is set with the keychainService option, it will be required to later fetch the value.
    • keychainAccessible (enum) --
      • iOS only: Specifies when the stored entry is accessible, using iOS's kSecAttrAccessible property. See Apple's documentation on keychain item accessibility. The available options are:
        • SecureStore.WHEN_UNLOCKED (default): The data in the keychain item can be accessed only while the device is unlocked by the user.
        • SecureStore.AFTER_FIRST_UNLOCK: The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user. This may be useful if you need to access the item when the phone is locked.
        • SecureStore.ALWAYS: The data in the keychain item can always be accessed regardless of whether the device is locked. This is the least secure option.
        • SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY: Similar to WHEN_UNLOCKED, except the entry is not migrated to a new device when restoring from a backup.
        • SecureStore.WHEN_PASSCODE_SET_THIS_DEVICE_ONLY: Similar to WHEN_UNLOCKED_THIS_DEVICE_ONLY, except the user must have set a passcode in order to store an entry. If the user removes their passcode, the entry will be deleted.
        • SecureStore.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY: Similar to AFTER_FIRST_UNLOCK, except the entry is not migrated to a new device when restoring from a backup.
        • SecureStore.ALWAYS_THIS_DEVICE_ONLY: Similar to ALWAYS, except the entry is not migrated to a new device when restoring from a backup.

Returns

A promise that will reject if value cannot be stored on the device.

SecureStore.getItemAsync(key, options)

Fetch the stored value associated with the provided key.

Arguments

  • key (string) -- The key that was used to store the associated value.
  • options (object) (optional) -- A map of options:
    • keychainService (string) -- iOS: The item's service, equivalent to kSecAttrService. Android: Equivalent of the public/private key pair Alias.
    NOTE If the item is set with the keychainService option, it will be required to later fetch the value.

Returns

A promise that resolves to the previously stored value, or null if there is no entry for the given key. The promise will reject if an error occurred while retrieving the value.

SecureStore.deleteItemAsync(key, options)

Delete the value associated with the provided key.

Arguments

  • key (string) -- The key that was used to store the associated value.
  • options (object) (optional) -- A map of options:
    • keychainService (string) -- iOS: The item's service, equivalent to kSecAttrService. Android: Equivalent of the public/private key pair Alias. If the item is set with a keychainService, it will be required to later fetch the value.

Returns

A promise that will reject if the value couldn't be deleted.