application.keychain: set() function
The set() function writes a string value. When the key already exists, its value is overwritten without an error.
Syntax
set(key, value[, { accessible }])Parameters
key
The key, a non-empty string.
value
The value, a string. Convert numbers, arrays, and objects to text first, for example with JSON.stringify(). For binary data, use setBytes().
options.accessible
Optional. The item's access level, one of five strings, defaulting to 'whenUnlockedThisDeviceOnly'. For the effect of each value, see Access levels.
It takes effect only when the item is first written: writing again to an existing key with a different accessible updates the value but keeps the access level, without an error (derived from reading the code; not verified in the simulator). To change the access level, call remove() first, then set().
Return value
A Promise that fulfills with undefined once writing is done.
Rejection cases:
accessibleis a string but not one of the five values:nameis'TypeMismatchError', andmessageisaccessible has no value "always"; expected one of:followed by the accepted values. The key isn't written.accessibleis'whenPasscodeSetThisDeviceOnly'and the device has no passcode set: writing fails (not verified in the simulator).- Other failures; see What you get on error.
Exceptions
TypeError (thrown immediately, without returning a Promise)
keyisn't a string, or is an empty string:set: key must be a non-empty string.valueisn't a string:set: value must be a string; use setBytes for binary.accessibleisn't a string:set: accessible must be a string.
Description
Calling set twice on the same key in a row without waiting leaves the value from the later call (derived from reading the code; not verified in the simulator).
Examples
async function saveRefreshToken() {
await application.keychain.set('refreshToken', 'r-456', {
accessible: 'afterFirstUnlockThisDeviceOnly',
});
console.log(await application.keychain.get('refreshToken'));
}
saveRefreshToken();Result: It prints r-456. After the user unlocks once following a restart, it can be read even while the device is locked (not verified in the simulator).
Corresponding iOS API
SecItemUpdate, or SecItemAdd when the item doesn't exist. accessible corresponds to kSecAttrAccessible; kSecAttrAccessibleWhenUnlocked is written 'whenUnlocked', and the rest likewise.