Overview

API reference

Every export of @apexnative/keychain and its entry points, with a page each: the signature, the parameters, what it returns, whether it can show the prompt, what it throws, and examples. Below, the rules every call follows.

Entry points

Import from	What it has
@apexnative/keychain	The storage, its options, the device capabilities, the errors
@apexnative/keychain/migrate	Moving the items of react-native-keychain and expo-secure-store into the package
@apexnative/keychain/compat	The functions of react-native-keychain over the package's storage
@apexnative/keychain/jest	The same API over a storage in memory, and keychainMock to drive it in tests
app.plugin.js	The Expo config plugin: "plugins": ["@apexnative/keychain"]

/migrate and /compat are separate so that an app that doesn't use them doesn't load them.

Storage

Export	Kind	What it is
keychain	Object	The storage of the default service: the bundle identifier, the application id
createKeychain	Function	A storage of its own service, with defaults for its calls
Keychain	Interface	The methods of a storage: strings, bytes, info, listing, sync calls, credentials
SetOptions, GetOptions	Types	The options of a write and of a read
ItemInfo	Type	What getItemInfo reports without a prompt
Credentials, CredentialsOptions	Types	A username and a password, and the server they are for

Options

Export	Kind	What it is
KeychainOptions	Type	The options of createKeychain
Accessible	Constants, type	When an item can be read
AccessControl	Constants, type	What unlocks an item
KeyStorage	Constants, type	Where Android keeps the item's key
Prompt	Type	The texts of the system prompt
AndroidOptions	Type	The options for Android only

Device capabilities

Export	Kind	What it is
getBiometryTypes	Function	The biometrics of the device that can unlock a key
canUseAccessControl	Function	Whether an item can be written with an accessControl now, and why not
isPasscodeSet	Function	Whether the device has a passcode, PIN or pattern
getBiometryState	Function	A token that changes when the enrolled biometrics change
getHardwareSecurityLevel	Function	Where Android keeps new keys; null on iOS
BiometryType	Constants, type	A biometric modality: faceID, fingerprint, …
HardwareSecurityLevel	Constants, type	strongbox, tee or software
AccessControlAvailability	Type	What canUseAccessControl answers

Errors

Export	Kind	What it is
KeychainError	Class	The error of every failed call: code, nativeCode, nativeDomain
KeychainErrorCode	Constants, type	Every code
isKeychainError	Function	Whether a value is a KeychainError, optionally with a given code
KeychainErrorDetails	Type	The native details of an error

Rules of every call

• Errors. Every call fails with a KeychainError: an async method rejects, a sync method throws. A missing value is null, never an error. A method without a value resolves to undefined.
• Checks first. Keys, values and options are checked in JavaScript before the native call, the same way on iOS and Android. A key that breaks the rules, a string with U+0000, an option with a wrong value, or an option name that doesn't exist throws INVALID_ARGUMENT.
• Prompts. Only reads of a protected item (getItem, getBytes, getCredentials, and migrateItem of a protected old item) can show the system prompt. Writes, removals, hasItem, getItemInfo, getAllKeys, clear, the sync methods and the device functions never do.
• Never weaker. An option means the same on both platforms. A device that can't give an item its protection fails the write; the item is never stored with less.
• Only its own items. The package reads, lists and removes only the items it wrote; those of other libraries are moved by /migrate.
• Platforms. Every export works on iOS and Android. On the web every call throws UNSUPPORTED; so does a call in an app without the native module (Expo Go, or an app not rebuilt after the install), with a message that says how to fix it. Importing the package never fails.