useTrustedDevices()
The useTrustedDevices() hook provides methods to check biometric trusted-device availability, enroll the current app installation, list and revoke credentials, and sign in returning users.
Returns
The useTrustedDevices() hook returns the following methods:
getAvailability()
Checks whether a trusted-device credential and private key are available locally for sign-in. Pass an id or identifierHint to check a specific credential. The function signature is:
function getAvailability(
params?: GetTrustedDeviceAvailabilityParams,
): Promise<TrustedDeviceAvailability>Parameters
getAvailability() accepts the following parameters (GetTrustedDeviceAvailabilityParams):
- Name
id?- Type
string- Description
The ID of the trusted-device credential to check. When omitted, Clerk checks the available local credential.
- Name
identifierHint?- Type
string- Description
A local-only user identifier hint used to select a matching credential.
Returns
getAvailability() returns the following values:
- Name
isAvailable- Type
boolean- Description
Whether a local credential and private key are available for trusted-device sign-in.
- Name
unavailableReason- Type
'environment_unavailable' | 'native_api_disabled' | 'feature_disabled' | 'unsupported_platform' | 'biometric_authentication_unavailable' | 'no_local_credential' | 'local_key_missing' | 'server_credential_missing' | 'server_credential_revoked' | null- Description
The reason trusted-device sign-in is unavailable. This value is
nullwhen sign-in is available.
list()
Lists active trusted-device credentials for the signed-in user. Returns a Promise that resolves to an array of TrustedDevice objects. The function signature is:
function list(): Promise<TrustedDevice[]>enroll()
Enrolls the current app installation as a biometric trusted device. Enrollment requires a Clerk session with a status of active or pending. Returns a Promise that resolves to the enrolled TrustedDevice object. The function signature is:
function enroll(params?: EnrollTrustedDeviceParams): Promise<TrustedDevice>Parameters
enroll() accepts the following parameters (EnrollTrustedDeviceParams):
- Name
deviceName?- Type
string- Description
A human-readable name stored with the trusted-device credential.
- Name
identifierHint?- Type
string- Description
A local-only user identifier hint stored with the credential for later selection.
- Name
reason?- Type
string- Description
The reason displayed in the system authentication prompt.
- Name
policy?- Type
'biometry_current_set' | 'biometry_any' | 'biometry_or_device_passcode'- Description
The local authentication policy used to protect the private key. Defaults to
'biometry_or_device_passcode'.'biometry_current_set': Requires a biometric from the currently enrolled set. Adding or removing biometric enrollment invalidates the private key.'biometry_any': Requires biometric authentication and allows biometric enrollment changes.'biometry_or_device_passcode': Requires biometrics to be available during enrollment. During authentication, it allows biometrics or the device passcode on iOS and biometrics or the device PIN, pattern, or password on Android 11 (API level 30) and later. Authentication remains biometric-only on Android 9 and 10.
revoke()
Revokes a trusted-device credential. If the credential belongs to the current app installation, Clerk also deletes its local private key. Returns a Promise that resolves to the revoked TrustedDevice object. The function signature is:
function revoke(id: string): Promise<TrustedDevice>Parameters
revoke() accepts the following parameter:
- Name
id- Type
string- Description
The ID of the trusted-device credential to revoke.
signIn()
Signs in with a locally enrolled trusted-device credential. The function signature is:
function signIn(params?: SignInWithTrustedDeviceParams): Promise<TrustedDeviceSignInResult>Parameters
signIn() accepts the following parameters (SignInWithTrustedDeviceParams):
- Name
id?- Type
string- Description
The ID of the trusted-device credential to use. When omitted, Clerk uses the available local credential.
- Name
identifierHint?- Type
string- Description
A local-only user identifier hint used to select a matching credential.
- Name
reason?- Type
string- Description
The reason displayed in the system authentication prompt.
Returns
signIn() returns the following values:
- Name
status- Type
SignInStatus- Description
The status of the sign-in attempt.
- Name
createdSessionId- Type
string | null- Description
The ID of the session created by a completed sign-in. Pass this value to setActive() to activate the session.
- Name
id- Type
string- Description
The ID of the trusted-device credential.
- Name
object- Type
'trusted_device'- Description
The resource object name.
- Name
platform- Type
'ios' | 'android'- Description
The platform associated with the credential.
- Name
appIdentifier- Type
string- Description
The native app identifier associated with the credential.
- Name
name- Type
string | null- Description
The human-readable credential name.
- Name
algorithm- Type
'ES256'- Description
The credential's signature algorithm.
- Name
status- Type
'active' | 'revoked'- Description
The credential's status.
- Name
createdAt- Type
Date- Description
The date when the credential was created.
- Name
updatedAt- Type
Date- Description
The date when the credential was last updated.
- Name
lastUsedAt- Type
Date | null- Description
The date when the credential was last used.
- Name
revokedAt- Type
Date | null- Description
The date when the credential was revoked.
How to use the useTrustedDevices() hook
To learn how to enroll a trusted device, sign in a returning user, and revoke a credential, see the biometric sign-in guide.
Feedback
Last updated on