Clerk Changelog

Why JWT?

JWT M2M tokens offer several advantages over opaque tokens:

• Networkless verification — JWTs can be verified locally using your instance's public key, without making a network request to Clerk's servers
• No verification cost — Opaque token verification costs $0.00001 per request, while JWT verification is free since it happens locally
• Self-contained — All necessary information (machine ID, claims, expiration) is embedded in the token itself
• Lower latency — Local verification is significantly faster than a network round-trip

When to use opaque tokens

Opaque tokens remain valuable for security-sensitive scenarios:

• Instant revocation — Opaque tokens can be invalidated immediately, while JWTs remain valid until they expire
• Maximum security — Opaque tokens do not contain any embedded information. Server-side verification is required to access payload data.

Getting Started

Dashboard

To generate your M2M token format:

1. Navigate to Machines⁠ in the Clerk Dashboard
2. Select the machine you want to generate the token for.
3. Select Generate token
4. Toggle Generate token as JWT
5. Select Create

SDK

// Create a JWT token on Machine A
const m2mToken = await clerkClient.m2m.createToken({
  tokenFormat: 'jwt',
})

// Send authenticated request to Machine B
await fetch('<machine-b-url>', {
  headers: {
    Authorization: `Bearer ${m2mToken.token}`,
  },
})

// Verify the token on Machine B — no network request needed
const verified = await clerkClient.m2m.verify({ token })

Pricing

We will begin charging for M2M token usage starting March 16, 2026. The pricing will be:

• $0.001 per token creation
• $0.00001 per token verification (opaque tokens only)

For more details, see the M2M tokens documentation and token formats documentation.

The @clerk/chrome-extension SDK now fully supports vanilla JavaScript (non-React) usage through createClerkClient() imported from @clerk/chrome-extension/client. A new Chrome Extension JS Quickstart guide is available to help you get started.

createClerkClient() for vanilla JS

Use createClerkClient() from @clerk/chrome-extension/client to initialize Clerk in a popup or side panel without React:

import { createClerkClient } from '@clerk/chrome-extension/client'

const clerk = createClerkClient({
  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
})

await clerk.load({
  allowedRedirectProtocols: ['chrome-extension:'],
})

background option for createClerkClient()

Whether you're using React or vanilla JS, createClerkClient() from @clerk/chrome-extension/client now accepts a background: true option for use in background service workers. This replaces the separate @clerk/chrome-extension/background import.

import { createClerkClient } from '@clerk/chrome-extension/client'

async function getToken() {
  const clerk = await createClerkClient({
    publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
    background: true,
  })

  if (!clerk.session) {
    return null
  }

  return await clerk.session?.getToken()
}

Deprecation: @clerk/chrome-extension/background

Importing createClerkClient from @clerk/chrome-extension/background is now deprecated. Both React and vanilla JS extensions should update to import from @clerk/chrome-extension/client with the background: true option instead.

We're excited to announce the latest major release of Clerk's SDKs, Core 3. With the release, we're investing in better customization primitives and agent-friendly APIs. Highlights include:

• Improved customization APIs: New hooks for building custom sign in, sign up, and checkout flows.
• Theme editor and interactive docs: Customize components visually and preview props live in the docs.
• Agent-optimized onboarding: Keyless mode for more SDKs: TanStack Start, Astro, and React Router.
• Modern React support: Improved support for apps that use concurrent rendering features.
• Performance improvements: Smaller bundles, faster token fetching, better offline handling.

Upgrade today

We've built an upgrade CLI that scans your codebase and applies codemods for most breaking changes. If you've used our upgrade tool before, the process is the same.

npx @clerk/upgrade

Core 3 requires Node.js 20.9.0+. For the full list of changes, upgrade prompts, and step-by-step instructions, see the Core 3 upgrade guide.

Improved customization APIs

We've redesigned the APIs for the useSignIn, useSignUp and useCheckout hooks, and introduced a new useWaitlist hook. These refreshed APIs make building custom auth UIs easier for humans and agents.

Previously, you needed to maintain your own state for attempt status, loading states, and error parsing. Now, it's all exposed from the hooks:

// signIn is stateful, updates will trigger re-renders
const { signIn, fetchStatus, errors } = useSignIn()

// Step methods map directly to the flow
await signIn.password({ emailAddress, password })
await signIn.emailCode.sendCode()
await signIn.emailCode.verifyCode({ code })

// Read the resource's status directly
signIn.status // 'needs_first_factor' | 'needs_second_factor' | 'complete'

// Built-in fetch state
fetchStatus // 'idle' | 'fetching'

// Structured field-level errors
errors.fields.identifier // "Couldn't find your account"
errors.fields.password // "Password is incorrect"

The same structure applies whether you're building a sign up form, a waitlist, or a checkout flow, so you don't need to learn a different API for each one. The hooks are designed to work with any component library, whether you're using shadcn/ui, Radix, or your own components.

We've also rewritten all of our custom flow documentation to use the new hooks.

Theme editor and interactive docs

We've launched a theme editor⁠ that lets you visually customize Clerk's prebuilt components and copy the resulting appearance prop configuration into your app. You can adjust colors, spacing, typography, and borders, and see the changes in real time. Give it a whirl and share your custom themes with us!

Our component documentation is now interactive too. You can tweak props, see live previews, and copy working code directly from the docs.

Agent-optimized onboarding for more frameworks

Keyless mode, the ability to try Clerk without creating an account or configuring API keys, now works with TanStack Start, Astro, and React Router. You can go from pnpm install to a working auth setup without leaving your editor. Great for agents!

Modern React support

Clerk now works correctly when your app is using React's concurrent features, including transitions, Suspense, and streaming SSR. Previously, Clerk's auth state synchronization could conflict with concurrent rendering, leading to stale state during useTransition navigations or hydration mismatches with streaming. Core 3 reworks how Clerk manages auth state internally to resolve these issues. No code changes are needed on your end.

Performance improvements

• Smaller bundles: React is now shared across all framework SDKs instead of being bundled separately with Clerk's components. This saves roughly ~50KB gzipped (the size of react + react-dom) for apps using components and framework-specific packages like @clerk/nextjs or @clerk/tanstack-react-start.
• Faster satellite domains: Previously, satellite domains triggered a Handshake redirect to the primary domain on every first page load, even for anonymous visitors. Core 3 introduces a satelliteAutoSync option (defaults to false) that skips the redirect when no session cookies exist. The handshake now only fires after an explicit sign in action, eliminating the unnecessary redirect for most satellite traffic.
• Better offline handling: getToken() previously returned null both when the user was signed out and when the device was offline. The latter was unintentional. It now throws a ClerkOfflineError when the network is unavailable, so you can more reliably handle being offline in your application.
• Optimized token fetching: getToken() now proactively refreshes session tokens in the background before they expire, so your app never has to wait for a token refresh mid-request. This eliminates intermittent blocking delays in apps that make frequent API calls, like AI chat apps with sequential requests.

Other updates

• Simplified package names: @clerk/clerk-react is now @clerk/react. @clerk/clerk-expo is now @clerk/expo. The upgrade CLI handles the rename.
• Unified <Show> component: <Protect>, <SignedIn>, and <SignedOut> are replaced by a single <Show> component. Use when="signed-in", when="signed-out", or pass a condition callback for authorization checks. In certain scenarios, these components still expose the content they are wrapping in your source code. We picked Show as the new name to make it clear that this utility should be only be used to control visibility. Learn more.

// Previously <SignedIn>
<Show when="signed-in">
  <Dashboard />
</Show>

// Previously <Protect>
<Show when={(has) => has({ role: 'admin' })}>
  <AdminPanel />
</Show>

• Automatic light/dark theme: Previously, you had to manually switch Clerk's component theme depending on the theme of your application. Now, Clerk's components automatically match your app's color scheme if it supports light and dark mode. No additional configuration needed. Learn more.
• Automatic Vite env detection: Clerk detects environment variables in Vite-based projects automatically. No more manually passing VITE_CLERK_PUBLISHABLE_KEY. Learn more.
• Portal provider: New UNSAFE_PortalProvider component lets you specify a custom container for Clerk's portaled UI elements (popovers, modals, tooltips). This solves a common issue when using Clerk components inside libraries like Radix Dialog or React Aria, where portaled elements would render to document.body and end up behind the dialog. Learn more.
• Frontend API proxy helper: clerkMiddleware in Next.js and Express now supports proxying requests to Clerk's Frontend API. Previously, you had to implement this yourself following the guide in our docs. Enable it with frontendApiProxy: { enabled: true } in your middleware config. Learn more.
• Types subpath exports: You can now import Clerk types directly from any SDK package (e.g. import type { UserResource } from '@clerk/react/types') instead of installing the separate @clerk/types package. @clerk/types has been deprecated.
• Next.js cache components support: Baseline support for Next.js's cache components. If you're using cache components, ClerkProvider should be placed inside <body> rather than wrapping <html>.
• Component changelog: A new centralized component changelog tracks visual and behavioral updates to prebuilt components, independent of SDK releases.

Deprecations

• Clerk Elements: Deprecated in favor of the redesigned hooks, which cover the same custom UI use cases with less complexity.
• @clerk/types: As mentioned above, the dedicated types package has been deprecated in favor of exposing types through existing SDKs.
• For additional deprecations and breaking changes, see the upgrade guide.

If you run into issues upgrading, reach out on Discord⁠ or contact support⁠. We're here to help. Happy building!

Understand how well your application retains organizations with the new organization retention report. Clerk automatically tracks how many organizations remain active after creation, enabling you to visualize how your organization retention is trending versus industry benchmarks.

Features

• Change the interval to see how your organization cohorts retain over the first 30 days, 8 weeks, and 3 months.
• Visualize how your retention is changing over time by comparing the last three or six cohorts.
• Set a goal shape to measure how your retention is improving towards industry benchmarks.
• View recent cohorts in progress, or toggle off 'show incomplete period' to see only cohorts with complete data.

You can now require multi-factor authentication (MFA) across your iOS and Android authentication flows with a single toggle.

This applies to both new users during sign-up and existing users when they sign in, ensuring MFA is completed before access is granted.

What's new

Requiring multi-factor authentication (MFA) now works end-to-end in prebuilt authentication flows for iOS and Android.

If a session is created in a pending state with a setup-mfa task, the SDK automatically routes users to the dedicated MFA setup flow instead of completing sign-in. Users can set up one of your enabled MFA methods, including Authenticator app (TOTP) and SMS verification code.

Getting started

To require MFA in your mobile application:

1. Navigate to Multi-factor⁠ in the Clerk Dashboard.
2. Enable one or more MFA strategies (Authenticator app or SMS verification code).
3. Turn on Require multi-factor authentication.

Once enabled, new users are prompted to set up MFA during sign-up, and existing users without MFA are prompted the next time they sign in.

To learn more, visit the setup MFA guide⁠.

What's new

• Shareable test URLs — From any enterprise connection (SAML or OIDC) in the Dashboard, use Copy Test URL to generate a one-time link. Share it with your customer or IT team so they can run a sign-in attempt against your connection.

• Test logs — Results of each test URL run (success or failure and details), so you can get more information for troubleshooting.

Getting started

In the Clerk Dashboard⁠, go to User authentication → SSO connections, open an enterprise connection, and complete the connection setup. Then use Copy Test URL to create and copy a test link. Share it with your customer to run a test sign-in; the attempt will appear under Test logs.