Skip to main content

useBiometricCredentials()

Important

This hook requires the @clerk/expo-biometrics package and a development build that includes it. It doesn't work in Expo Go.

The useBiometricCredentials() hook provides methods to check biometric credential availability, enroll the current app installation, list and revoke credentials, sign in returning users, and reverify the active session.

Installation

Install @clerk/expo-biometrics, then rebuild your development build:

terminal
npx expo install @clerk/expo-biometrics

Import the hook from @clerk/expo/biometrics:

import { useBiometricCredentials } from '@clerk/expo/biometrics'

Without @clerk/expo-biometrics, the hook's methods throw an error that explains how to install it. To add the Face ID usage description on iOS, see the biometric sign-in guide.

Important

The iOS Simulator can't create the hardware-backed keys required for biometric credentials, so getAvailability() reports biometric_authentication_unavailable there. Test on a physical iPhone.

Returns

The useBiometricCredentials() hook returns the following methods:

getAvailability()

Checks whether a biometric 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?: GetBiometricCredentialAvailabilityParams,
): Promise<BiometricCredentialAvailability>

Parameters

getAvailability() accepts the following parameters (GetBiometricCredentialAvailabilityParams):

  • Name
    id?
    Type
    string
    Description

    The ID of the biometric 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 biometric 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 biometric sign-in is unavailable. This value is null when sign-in is available.

list()

Lists active biometric credentials for the signed-in user. Returns a Promise that resolves to an array of BiometricCredentialExpo Icon objects. The function signature is:

function list(): Promise<BiometricCredential[]>

enroll()

Enrolls the current app installation as a biometric credential. Enrollment requires a Clerk session with a status of active or pending. Returns a Promise that resolves to the enrolled BiometricCredentialExpo Icon object. The function signature is:

function enroll(params?: EnrollBiometricCredentialParams): Promise<BiometricCredential>

Parameters

enroll() accepts the following parameters (EnrollBiometricCredentialParams):

  • Name
    identifierHint?
    Type
    string
    Description

    A local-only user identifier hint stored with the credential for later selection.

  • Name
    name?
    Type
    string
    Description

    A human-readable name stored with the biometric credential.

  • 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_current_set'.

    • '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 sign-in, 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. Sign-in remains biometric-only on Android 9 and 10.
  • Name
    reason?
    Type
    string
    Description

    The reason displayed in the system authentication prompt.

reverify()

Reverifies the active session with a locally enrolled biometric credential on iOS or Android. The function signature is:

function reverify(params?: ReverifyWithBiometricsParams): Promise<BiometricReverificationResult>

Important

Biometric reverification on iOS and Android requires an active session and a credential enrolled with 'biometry_current_set'. Existing credentials keep the policy selected at enrollment. getAvailability()Expo Icon checks sign-in availability and doesn't establish whether a credential supports reverification.

If authentication is canceled or fails, the promise rejects. Use isBiometricCredentialError() from @clerk/expo/biometrics to inspect biometric error codes, such as biometric_authentication_canceled or biometric_credential_policy_incompatible. If a credential uses an incompatible policy, offer another verification method.

If biometric verification of the first factor leaves the attempt at needs_second_factor, reverify() returns that status instead of reusing the same credential, so finish with another verification method. When verification completes, Clerk updates the session and refreshes its token. It doesn't create a new session or require a call to setActive().

Parameters

reverify() accepts the following parameters (ReverifyWithBiometricsParams):

  • Name
    level?
    Type
    'first_factor' | 'second_factor' | 'multi_factor'
    Description

    The requested verification level. Defaults to 'first_factor'. Use 'second_factor' to reverify the second factor or 'multi_factor' to request both factors. The server can adjust the level based on the user's enrolled factors; check the returned level for the effective requirement.

  • Name
    reason?
    Type
    string
    Description

    The reason displayed in the system authentication prompt.

Returns

reverify() returns the following values:

  • Name
    id
    Type
    string | null
    Description

    The ID of the session verification, or null if the server doesn't provide one.

  • Name
    level
    Type
    SessionVerificationLevel | (string & {})
    Description

    The verification level returned by the server. Known values are 'first_factor', 'second_factor', and 'multi_factor'. This can differ from the requested level based on the user's enrolled factors. The type also accepts other strings for forward compatibility.

  • Name
    session
    Type
    SessionResource
    Description

    The updated active session. Its ID is unchanged. When verification completes, Clerk refreshes its token before the promise resolves, so subsequent requests use the updated verification state.

  • Name
    status
    Type
    SessionVerificationStatus | (string & {})
    Description

    The verification status. Known values are 'needs_first_factor', 'needs_second_factor', and 'complete'. The type also accepts other strings for forward compatibility. Only 'complete' indicates successful reverification.

revoke()

Revokes a biometric 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 BiometricCredentialExpo Icon object. The function signature is:

function revoke(id: string): Promise<BiometricCredential>

Parameters

revoke() accepts the following parameter:

  • Name
    id
    Type
    string
    Description

    The ID of the biometric credential to revoke.

signIn()

Signs in with a locally enrolled biometric credential. The function signature is:

function signIn(params?: SignInWithBiometricsParams): Promise<BiometricSignInResult>

Parameters

signIn() accepts the following parameters (SignInWithBiometricsParams):

  • Name
    id?
    Type
    string
    Description

    The ID of the biometric 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
    createdSessionId
    Type
    string | null
    Description

    The ID of the session created by a completed sign-in. Activate it with result.setActive({ session: result.createdSessionId }).

  • Name
    setActive
    Type
    (params: SetActiveParams) => Promise<void>
    Description

    Activates a session. Call it with createdSessionId after the sign-in reaches complete. It's the same function as setActive().

  • Name
    signIn
    Type
    SignIn
    Description

    The sign-in resource, for continuing any remaining authentication steps when the sign-in isn't complete.

  • Name
    status
    Type
    SignInStatus
    Description

    The status of the sign-in attempt.

Types

BiometricCredential

  • Name
    algorithm
    Type
    'ES256'
    Description

    The credential's signature algorithm.

  • Name
    appIdentifier
    Type
    string
    Description

    The native app identifier associated with the credential.

  • Name
    createdAt
    Type
    Date
    Description

    The date when the credential was created.

  • Name
    id
    Type
    string
    Description

    The ID of the biometric credential.

  • Name
    lastUsedAt
    Type
    Date | null
    Description

    The date when the credential was last used.

  • Name
    name
    Type
    string | null
    Description

    The human-readable credential name.

  • Name
    object
    Type
    'trusted_device'
    Description

    The resource object name.

  • Name
    platform
    Type
    'ios' | 'android'
    Description

    The platform associated with the credential.

  • Name
    revokedAt
    Type
    Date | null
    Description

    The date when the credential was revoked.

  • Name
    status
    Type
    'active' | 'revoked'
    Description

    The credential's status.

  • Name
    updatedAt
    Type
    Date
    Description

    The date when the credential was last updated.

How to use the useBiometricCredentials() hook

To learn how to enroll a biometric credential, sign in a returning user, reverify an active session, and revoke a credential, see the biometric sign-in guide.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub