@clerk/expo

Rewrite the sync between the Clerk JS client and the native Clerk SDK. Both now share a single device token stored by the native SDK. This fixes a stale token in the app's tokenCache signing out a session that was signed in natively, and the two SDKs ending up on different tokens when both rotated the device token at the same time.

If you use the native components, update @clerk/expo-native-components to 0.3.0 or later and ship a new app build. Builds made with an older version render the native components blank, so don't deliver this version to them as an over-the-air update. With EAS Update, the fingerprint runtime version policy keeps those builds from receiving it. With any other policy, change your runtime version when you make this upgrade.

Show @clerk/expo warnings and errors in development builds. The build previously removed them.

Add Expo SDK 58 support.

Fix iOS users being signed out when the keychain can't be read for a moment, for example when the app launches in the background before the device has been unlocked since a restart.

Native components now respect the proxyUrl passed to <ClerkProvider> and route Frontend API requests through the configured proxy. Applying the proxy requires a new app binary; a JS-only OTA update safely keeps the previous behavior.

Introduce @clerk/expo-native-components, a new package that the native components (AuthView, UserButton, UserProfileView) now require. Install it and rebuild your app.

npx expo install @clerk/expo-native-components

If it's missing, rendering a native component throws an error with these same steps. Install the package before you ship this version in an over-the-air update, because the error is thrown at runtime and not at build time.

Import the native components and their hooks from @clerk/expo/native-components. @clerk/expo/native is deprecated. It still works and logs a warning in development.

Apps that don't install the package no longer include the Clerk iOS and Android SDKs and no longer require iOS 17. On Android, those apps also stop migrating biometric credentials enrolled with earlier versions of @clerk/expo, so users who weren't migrated by an earlier release need to enroll again.

Add revokeCurrentDeviceCredential() to useBiometricCredentials(). It revokes this device's biometric credential for the signed-in user, so you no longer need to store the ID from enroll(). It returns the revoked credential, or null if there is nothing to revoke. Call it before signing out, since it needs a session.

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

const { revokeCurrentDeviceCredential } = useBiometricCredentials();

await revokeCurrentDeviceCredential();

Deprecate useLocalCredentials(). It will be removed in the next major version. To keep the same flow, store the credentials with expo-secure-store and its requireAuthentication option, then sign in with the stored identifier and password.

Fix the close button of a dismissible <AuthView /> doing nothing on iOS when the view is rendered inline instead of inside a modal. Tapping it now calls onDismiss.

Fix useLocalCredentials throwing "Invalid key provided to SecureStore" when the publishable key ends with base64 padding (=).

Introduce @clerk/expo-biometrics, a new package that useBiometricCredentials() now requires. Install it and rebuild your app:

npx expo install @clerk/expo-biometrics

If it's missing, the hook throws an error with these same steps.

Import the hook from @clerk/expo/biometrics:

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

Importing it from @clerk/expo still works, but it logs a deprecation warning and will be removed in the next major version.

Add useBiometricCredentials().reverify() for first-, second-, and multi-factor verification of the active session on iOS and Android. If the first factor still requires a second factor, reverification continues the same attempt automatically. Successful verification refreshes the JavaScript session token without creating a new session.

New biometric enrollments default to biometry_current_set, requiring biometrics without device-passcode fallback. Existing credentials keep their original policy; reverification on iOS and Android requires the stronger policy and returns biometric_credential_policy_incompatible for older, weaker credentials. Apps should offer another verification method in that case. Reverification requires an updated native development build.

Fix useLocalCredentials() reporting hasCredentials as true after the biometric prompt is cancelled during setCredentials(). A cancelled prompt now leaves the stored credentials unchanged, so authenticate() no longer fails with a missing password.

Fix the offline resource cache so an app that switches Clerk instances no longer starts offline with the previous instance's cached user and session.

Fix the deprecated useOAuth() hook crashing when the sign-in attempt has no external verification redirect URL. It now throws a Clerk error, matching useSSO().

Update Clerk Dashboard links in option descriptions, error messages, and READMEs to use the active-instance shortcut (https://dashboard.clerk.com/~/…) instead of the legacy /last-active?path=… URL.

useSSO() now accepts oidcPrompt and oidcLoginHint and forwards them to the sign-in request.

Keep post-authentication prompts open in the native AuthView when the Clerk iOS SDK configuration refreshes.

Fix the Android <AuthView> rendering no sign-in form when it is opened within a couple of seconds of isLoaded turning true. The native view now recreates itself once the Clerk Android SDK finishes loading instead of staying empty until it is dismissed and reopened.

Add useBiometricCredentials() and biometric credential types for enrollment, management, and biometric sign-in, backed by clerk-ios 1.5.0 and clerk-android 1.1.4. The previous trusted-device exports, including useTrustedDevices(), remain available as deprecated aliases and will be removed in the next major release.

Fix AuthView's onDismiss never firing on iOS when isDismissible is false. The callback now runs once the auth flow completes, matching Android, so an app-owned modal or screen wrapping the view can close after sign-in.

Add iOS and Android APIs for biometric trusted-device enrollment, sign-in, availability, listing, and revocation, including structured native error codes. Trusted-device sign-in synchronizes the JS client before resolving and returns the JS sign-in resource and setActive() so apps can continue second-factor, new-password, or client-trust steps. Add useAuthViewState() for keeping a non-dismissible root <AuthView /> mounted through an optional trusted-device enrollment prompt, and support configuring the Face ID permission message through the Expo config plugin.

import { useTrustedDevices } from '@clerk/expo';

export function useBiometricSignIn(identifierHint: string) {
  const { enroll, getAvailability, signIn } = useTrustedDevices();

  // Call after the user completes a normal sign-in.
  const enableBiometricSignIn = () =>
    enroll({
      identifierHint,
      reason: 'Use biometrics to sign in next time.',
    });

  // Call when the user returns to sign in.
  const signInWithBiometrics = async () => {
    const { isAvailable } = await getAvailability({ identifierHint });

    if (!isAvailable) {
      return null;
    }

    const result = await signIn({
      identifierHint,
      reason: 'Use biometrics to sign in.',
    });

    // Continue any remaining steps through result.signIn.
    return result;
  };

  return { enableBiometricSignIn, signInWithBiometrics };
}

Surface Android Google Sign-In provider failures instead of silently treating them as a cancelled sign-in.

Android's Credential Manager reports failures such as an unregistered OAuth client through the same cancellation exception it uses for a dismissed account chooser, so startGoogleAuthenticationFlow() resolved with no session and no error. Those failures now reject with a GOOGLE_SIGN_IN_ERROR, while dismissing the chooser still resolves with createdSessionId: null.

If you call startGoogleAuthenticationFlow() without a try/catch, add one to handle the rejection.

Add push-only customDestinations to the native UserProfileView and UserButton, allowing custom profile pages to navigate forward without adding another row to the profile root.

Preserve native user profile custom pages across tab switches and display their labels as native navigation titles on iOS.

Add custom user profile pages to the native UserProfileView and UserButton components. Use content to render a React Native screen or href to open an external URL.

import { UserButton, UserProfileView } from '@clerk/expo/native';
import type { UserProfileCustomPage } from '@clerk/expo/native';

const customPages: UserProfileCustomPage[] = [
  {
    path: 'api-keys',
    label: 'API keys',
    icon: 'key',
    content: <APIKeysView />,
  },
  {
    path: 'docs',
    label: 'Docs',
    icon: 'book',
    href: 'https://clerk.com/docs',
  },
];

<UserProfileView customPages={customPages} />;

<UserButton userProfileProps={{ customPages }} />;

Fix a race on Android where the native module refreshed the client every time the app returned to the foreground, which could mint a duplicate client during browser SSO completion and cause 401 authentication_invalid errors right after signing in. The native SDK is now initialized with its foreground client refresh disabled, since the JavaScript layer owns client state. Session token refresh and shared session sync are unaffected.

Align Android OkHttp dependencies to compatible versions so Clerk native networking and React Native can run without a mixed OkHttp 4 and 5 classpath.

Add an experimental ClerkProvider option to disable native client synchronization when Clerk native components are not used.

Add an experimental useSSO() hook at @clerk/expo/experimental that uses future auth resources and activates completed SSO sessions automatically.

import { useSSO } from '@clerk/expo/experimental';

const { startSSOFlow } = useSSO();

await startSSOFlow({
  strategy: 'oauth_google',
});

Support pushing the native UserProfileView and AuthView onto your app's own navigation stack.

New optional onHostBack prop shows a back button on the component's root screen and calls you when it is tapped. The component keeps its own navigation chrome, so screen titles, back buttons, swipe-back, and transitions inside the component stay native — hide your route's header and pop your route from the callback:

<Stack.Screen options={{ headerShown: false }} />
<UserProfileView isDismissible={false} onHostBack={() => router.back()} />

The component never leaves the route on its own, so react to auth state for flow completion — either swap the content in place or pop the route.

Existing usage is unaffected: the prop is optional, and the components render exactly as before without it. Requires the corresponding clerk-ios and clerk-android SDK releases.

Fix JS auth state recovery after rejecting a divergent native client so signed-in sessions can still sign out.

Introduce the useHostedAuth() hook for signing users in or up through Clerk's hosted Account Portal from native Expo apps.

import { useHostedAuth } from '@clerk/expo/hosted-auth';

const { startHostedAuth } = useHostedAuth();

// Opens Account Portal on the sign-in page
await startHostedAuth();

// Or open the sign-up page first
await startHostedAuth({ mode: 'sign-up' });

Add a logo prop to the native AuthView, allowing Expo apps to replace the dashboard-configured logo with custom React Native content on Android and iOS.

Keep the active session when a native client change resolves to a different, signed-out client. The check that discards those clients compared a reference that the refresh had already mutated, so it never engaged and the signed-out client was applied over the current session.