@clerk/clerk-js

Support passkeys as a second factor during sign-in and session reverification.

When a user has a passkey, the prebuilt <SignIn/> and <UserVerification/>
components preselect it as the second factor, as they already do for the first
factor. Other methods stay available under "Use another method".

To use it, your instance must allow passkeys to satisfy the second factor. This
is on by default for instances created after 2026-07-08, and can be turned on
in the Dashboard for older ones. Web apps also need to opt in to the passkey
second factor update in the Dashboard.

If you build a custom flow, supportedSecondFactors can now include passkey.
Call signIn.authenticateWithPasskey() to complete it.

Passkeys are no longer preselected, for either factor, where the SDK reports
that WebAuthn is unavailable (for example, Electron apps without passkey
support enabled).

Fix oidcPrompt being ignored for OAuth strategies in signIn.sso() and signIn.authenticateWithRedirect(). The value is now sent when the sign-in is created, so a prompt such as select_account reaches the OAuth provider.

session.getToken() no longer skips the network request when navigator.onLine reports false. Some environments, such as Chrome behind certain VPN clients, can report offline while the network works, which caused every token refresh to fail with clerk_offline. HTTP errors from the Frontend API, including ones with non-JSON bodies such as a proxy's HTML 502, are now surfaced as-is instead of being relabeled as ClerkOfflineError. When a resource cache is configured (e.g. Expo), a 5xx response during startup now falls back to the cached resources, and non-JSON 5xx responses no longer clear the Chrome extension's stored development browser token.

Add a role mapping step to the self-serve Directory Sync setup in <OrganizationProfile />. Organization admins can now assign an organization role to each directory group their identity provider pushes, set which group wins when a member belongs to several, and turn role syncing on or off. Members in no mapped group keep the organization's default role. The step is read-only for members without the org:sys_memberships:manage permission and while the organization's role set is being migrated.

Add an enterpriseConnectionsUrl option to handleRedirectCallback() and <AuthenticateWithRedirectCallback />. When the Clerk API asks an OAuth sign-up to choose between several enterprise connections for the same email domain, the callback navigates to this URL, which defaults to the enterprise-connections route of your sign-up page.

Fix <HandleSSOCallback /> dropping the error when a Clerk Protect challenge fails on the SSO callback. The error is now available on errors from useSignIn() or useSignUp(), and a failed sign-up challenge calls navigateToSignUp instead of navigateToSignIn.

SAML enterprise connections can trust several Identity Provider signing certificates at once. EnterpriseConnection.samlConnection now includes idpCertificates, every trusted certificate with its validity window, and organization.createEnterpriseConnection() and organization.updateEnterpriseConnection() accept saml.idpCertificates, an array that replaces the connection's whole set. The single saml.idpCertificate input is deprecated in favor of the array; it keeps working and still replaces the whole set.

Add experimental APIs for biometric sign-in in native apps. This includes the trusted_device strategy for sign-in and session reverification, nativeSettings on the auth config, and __experimental_ methods on User for managing biometric credentials. These may change in minor releases.

Custom flows built with useSignIn() and useSignUp() now handle Clerk Protect challenges for you. When a sign-in or sign-up method gets a challenge, Clerk shows it in a modal and the method returns once the user passes it. For SSO, the challenge appears when the user comes back to <HandleSSOCallback />. Classic resource methods such as clerk.client.signIn.create(), and apps without Clerk's UI loaded, still return with protectCheck set, as before.

The Solana wallet picker downloads about 2 KB instead of about 306 KB, and installing @clerk/ui or @clerk/clerk-js no longer pulls in React Native, Metro, and @solana/web3.js. The picker now lists only wallets that can complete Sign in with Solana, so the Mobile Wallet Adapter option that appeared on Android Chrome is gone.

Support Google Workspace directories in Directory Sync. Organization admins can upload a service account key and delegated admin email from the setup flow, start a sync on demand, and see the result of the last one. DirectorySync gains setCredentials(), sync(), getSyncStatus(), and credentialsConfigured.

Capture authentication timezones so Clerk emails can display timestamps in a stored user timezone.

Fix abandoned passkey registrations counting toward the limit on unverified identifications. Cancelling or failing the browser passkey prompt left a pending registration on the account that is hidden from the user's passkey list, so it could silently block adding an email address or phone number until it expired. The pending registration is now removed as soon as the prompt is abandoned. In <UserProfile />, the "Add a passkey" button also shows a loading state while a registration is in progress, and a failed attempt no longer leaves its error banner on screen after a later attempt succeeds.

Fix enterprise SSO sign-ins erroring instead of showing a verification challenge raised while handing off to the identity provider.

If you use the prebuilt <SignIn /> component, there is nothing to do. If you have Clerk Protect enabled and call signIn.authenticateWithRedirect() or signIn.authenticateWithPopup() from a custom sign-in flow, catch a ClerkRuntimeError with code protect_check_required and show the verification challenge, to avoid a stalled sign-in.

That error means a verification challenge has to be completed before the sign-in can redirect. It replaces the generic "not supported" error these methods threw before. When it is thrown, the sign-in is gated: signIn.protectCheck is set, or its status is needs_protect_check. For enterprise SSO, run the challenge and then call authenticateWithRedirect() again with continueSignIn: true. If the server has already prepared the redirect, the sign-in continues to the identity provider and the challenge runs when it returns, so no error is thrown.

The "Add members" card on the SSO allow list page of <OrganizationProfile /> now offers two ways to add people: by email address, or every member with a given role at once. Members whose email address is not served by one of the organization's enterprise connections are skipped. When nothing could be added the card stays open and says why, and when some were added it moves to a success step that reports how many were skipped.

For custom flows, organization.ssoBypassAllowlist gains addUsers({ userIds }), which calls the new bulk endpoint in batches of 100 and returns the added entries together with the users that could not be added and why.

Inputs marked to be ignored by password managers now also carry the Bitwarden, LastPass and Dashlane opt-out attributes, so those extensions stop offering to fill fields such as the allow list email address.

The member picker that the "Add member" card shipped with in 4.18.0 is gone, and so are its localization keys under organizationProfile.securityPage.ssoBypassPage.addForm: memberLabel, memberPlaceholder, changeButton and noResults. The feature was never enabled on any instance, so no application depends on them.

New customization handles: the organizationProfileSecuritySsoBypassEmailInput, organizationProfileSecuritySsoBypassRoleWarning, organizationProfileSecuritySsoBypassFailure and organizationProfileSecuritySsoBypassBulkResult appearance elements.

Show the provider logo next to each connection name on the enterprise account chooser.

Fix <OAuthConsent /> rendering a blank page when reached through the redirect after completing <SignIn /> or <SignUp />.

Rename the SSO fallback sign-in flow to SSO bypass, matching the name the feature ships under. The sign-in resource's ssoFallbackFirstFactors is now ssoBypassFirstFactors and reads the sso_bypass_first_factors field from the API, the signIn.ssoFallback localization keys are now signIn.ssoBypass, and the ssoFallback card action element id is now ssoBypass. The flow has not been enabled on any instance, so no application is affected by the old names going away.

Add the ability for Organization admins to manage the SSO bypass allowlist from the Security page of <OrganizationProfile />.

For custom flows, organization.ssoBypassAllowlist exposes getUsers(), addUser({ userId }) and removeUser(userId).

Introduce self-serve Directory Sync (SCIM) capabilities and related functionality.

Add the SSO fallback sign-in flow to <SignIn />, for enterprise users the instance has allowlisted to sign in with an email code when they cannot reach their identity provider.

For such a user the sign-in no longer redirects straight to the identity provider. It shows the SSO action — or the connection picker, when several connections serve the address — alongside a "Can't use SSO?" link leading to the standard email code step, which carries a notice that the organization requires single sign-on and that the attempt is recorded. Users without a fallback, and instances without the feature, are unaffected.

Custom flows can read the same factor from the new ssoFallbackFirstFactors property on the sign-in resource. The flow adds the signIn.enterpriseSSO and signIn.ssoFallback localization keys and the ssoFallback card action element id.

Update the @tanstack/query-core dependency range to ^5.101.4.

Complete local sign-out while offline when cached resources surface a network error.

Add an authenticated OAuth device verification component and workflow hook for approving or denying OAuth Device Authorization Grant requests.

Fix oidcPrompt and oidcLoginHint being silently dropped from the Frontend API request in user.createExternalAccount() and externalAccount.reauthorize(). Both parameters were already accepted by the public types but never serialized, so providers such as Google would fall back to their default prompt behavior. They are now sent as oidc_prompt and oidc_login_hint.

Fix development instance initialization when a stale dev browser value is rejected by clearing the value and retrying the environment and client requests.

Fix an issue where a verification that was still progressing normally could be cancelled and reported to the user as having timed out.

Fixes an issue where OAuth account transfers that needed additional verification were returned to the beginning of sign-in.

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 }} />;

Internal improvements to Clerk Protect. No action is required, and instances that do not use Protect are unaffected.

Billing applied-discount snapshots now include optional durationInCycles. Payment attempt and statement UIs use the original discount length instead of cycles remaining, and omit the duration copy when it is unavailable.

Fix native OAuth transport flows (e.g. @clerk/electron) breaking out of modal components and failing with "Redirect url mismatch" errors.

Intermediate OAuth callback steps (sign-in to sign-up transfer, continue, MFA factors, password reset) now navigate inside the component's own router instead of navigating the app window to an internal Clerk route. Transport flows also always send the registered transport callback URL as the completion redirect, so production instances no longer reject sign-in or sign-up requests when a page-derived URL was picked up as the completion redirect.

Add <InviteMembersButton />, a control component that opens the organization invite-members form in a modal when clicked, working like <SignInButton mode="modal">.

Wrap your own button (or omit children for a default one). The button requires an active organization and should be rendered for members who can manage memberships (org:sys_memberships:manage). Opening it without an active organization or that permission is a no-op in production, and throws a descriptive error in development.

import { InviteMembersButton } from '@clerk/nextjs';

<InviteMembersButton>
  <button>Invite members</button>
</InviteMembersButton>;

This also adds Clerk.openInviteMembers() and Clerk.closeInviteMembers() for opening and closing the modal programmatically.

Support sign-in-or-sign-up combined flow with Clerk <SignIn> component

when strict enumeration protection is enabled.

On development instances, <SignIn> now logs a warning when the sign-in-or-up flow is rendered on an instance that has both password and strict enumeration protection enabled. In that configuration visitors without an account are routed to the password screen and cannot complete a sign-up, so the warning names both settings and how to resolve them.

Recover from partitioned-cookie startup races by removing stale non-partitioned cookies when partitioned cookies become available.

Complete the Safari ITP cookie refresh when setActive({ redirectUrl }) navigates.

Safari's ITP caps the client cookie at 7 days when it is re-issued from a fetch, so setActive() routes its redirect through /v1/client/touch to restore the full lifetime. That navigation was immediately followed by a second one to the undecorated redirect URL, which superseded it and aborted the touch request before it completed, leaving the cookie capped.

This applies to flows that pass redirectUrl without a navigate callback — email link sign-in, the password reset success screen, the OAuth popup flow, and direct setActive({ session, redirectUrl }) calls — in apps where Clerk performs a full page navigation rather than handing off to a router. Users still landed on the correct page, so the only symptom was Safari sessions ending after 7 days and returning devices being challenged as if they were new.

Enable self-serve OIDC configuration for every application. Organization admins can now select an OIDC provider in the <OrganizationProfile /> Security tab without the experimental.oidcSelfServe option, and existing OIDC connections open their configuration steps instead of the unsupported-provider state. The experimental.oidcSelfServe option no longer does anything and can be removed from <ClerkProvider /> and Clerk.load().

Apply the Safari ITP cookie refresh on sign-out.

Signing out re-issues the client cookie from a fetch, which Safari's ITP caps at 7 days. The client outlives sign-out, and it is what Client Trust uses to recognize a known device, so the cap meant a user who signed out and came back more than a week later was treated as being on a new device and challenged for a second factor.

signOut() now routes its redirect through /v1/client/touch when the client cookie is close to expiring, the same workaround setActive() already applies after sign-in. The redirect is left unchanged when no refresh is needed.

This covers signOut() calls that navigate to a redirect URL, including <UserButton /> and <SignOutButton />. Passing your own callback to signOut(callback) still navigates on your behalf and is not decorated.

Add support for configuring custom OpenID Connect enterprise connections through the Organization Profile.

Expose whether an organization member has been deprovisioned, and mark deprovisioned members as inactive in the Organization Profile.

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.

Fix the standalone <APIKeys /> component failing to render when an organization is active and user API keys are disabled but organization API keys are enabled. The component now correctly checks the user API keys setting only when no organization is active.

Bias proactive session token refresh ownership toward the focused browser tab and poll more often while focused in multi-tab apps.

When running in a browser context, session token requests now include a tab_state parameter (focused, visible, or hidden) so the backend can distinguish foreground from background token refreshes. The parameter is omitted in environments without a document, such as extension service workers.