Clerk Changelog

Inspect transactional email delivery events from the Clerk Dashboard.

Email Logs are now available in public beta for production instances. The new Email Logs page in the Clerk Dashboard gives you a reverse-chronological view of transactional email delivery events, so you can debug delivery issues without leaving the Dashboard.

Use Email Logs to understand what happened to an email after Clerk sent it, including whether the receiving mail service accepted it, whether delivery was delayed or failed, and whether the user opened or clicked it. You can filter logs by recipient email address, IP address, message ID, time range, and event type.

Select any log entry to view its details, including delivery status, response or bounce reason, related metadata, and the original provider payload when available.

Get started

Open Email Logs from the Logs section of the Clerk Dashboard. For workspaces using custom roles and permissions, grant the Email logs read permission to the roles that should have access.

View your largest organizations by member count to understand how usage is distributed across your userbase, spot outliers, and track account growth.

Read more

Render Clerk components without a card wrapper using the new elevation appearance option.

Read more

The remaining Directory Sync features — groups and custom attributes mapping — are now generally available, completing the SCIM GA rollout.

Read more

OAuth Applications can now request organization context, letting users pick an org during the OAuth flow and giving clients an org_id claim.

Read more

An events stream of auth, billing, and orgs events across your applications

A new Logs⁠ page has been introduced into the Clerk Dashboard meant to give increased visibility into the Clerk-driven events across your applications. Application Logs track things like sign-ins, sign-ups, user updates, organization changes, billing events, and many more — enabling more detailed debugging and improved observability for your business.

Filtering and search

The logs page displays a reverse-chronological feed of events and you can narrow results using filters:

• Event type — Filter by event type (e.g., user.created, sign_in.completed). Supports trailing wildcards (e.g., sign_in.*).
• Actor — Filter by the user or API key that triggered the event.
• Subject — Filter by the resource ID being acted upon (e.g., a user ID or organization ID).
• Trace ID — Correlate events across systems using a distributed trace ID.
• Device — Filter by device ID.
• Date range — Scope results to a specific time window.

Select any log entry to view its full details, including event metadata and a JSON payload containing additional information related to the event.

Get started

Application Logs are available for all plans with varying levels of retention; see our pricing page for more details. You can access the Logs view⁠ today in the Clerk Dashboard or read the full documentation to learn more.

Going forward

App logs are just the start. We're hard at work on additional observability including Email, SMS, and Administrative logs for actions taken by your app's admins within the Clerk Dashboard and the new Clerk CLI. Stay tuned for more.

Clerk CLI is a (surprise, surprise) command-line tool for setting up and managing Clerk directly from your terminal or agentic harness. It's open source⁠ and available for you to use today.

The Clerk CLI gives both developers and agents a scriptable, terminal-based interface to Clerk so they can avoid click-ops and build faster.

Key commands

• clerk init — Detects your framework, scaffolds Clerk into your project, and gets auth ready to configure. This is the fastest way to start using Clerk in an existing or new project.

• clerk config — Manage your application's settings directly from the command line. Choose sign-in methods, configure redirects, set session policies - everything you'd normally do in the dashboard, now in code.

• clerk api — Interact with the Clerk API directly. Fetch users, organizations, sessions, and all other resources all through one command.

Try it

Use a script runner...

bunx clerk init

...or install the CLI globally and try it out today:

bun add -g clerk
clerk init

npm install -g clerk
clerk init

pnpm install -g clerk
clerk init

yarn global add clerk
clerk init

brew install clerk/stable/clerk
clerk init

curl -fsSL https://clerk.com/install | bash
clerk init

Read the full documentation or run clerk --help to see the full list of commands and options to get started.

What's next?

This is the first release of the Clerk CLI and we're working on adding more commands and features along the way to make it even more powerful.

For example, we're hard at work on clerk deploy — a single command to validate your auth setup and push it live. Deploy will handle syncing your local configuration to production, so you can go from development to launch without switching contexts.

Contributor

Clerk

API keys are now generally available as of April 6th. Part of the machine authentication suite, API keys let your users create credentials that delegate access to your application's API on their behalf.

Pricing

Billing is now active. Each month includes a free allocation:

• 1,000 key creations, then $0.001 per creation
• 100,000 key verifications, then $0.00001 per verification

Get Started

• API keys guide: Complete walkthrough of enabling and using API keys
• Backend SDK reference: Full API for creating, listing, verifying, and revoking keys
• Dashboard⁠: Enable API keys for your application

Directory Sync is now available to all users, with new support for custom attribute mapping and automatic role assignment from IdP groups.

Directory Sync (SCIM) is now generally available and enabled for all users. When users are added, updated, or removed in your identity provider, those changes are automatically reflected in Clerk, without any manual account management.

The following enhancements to Directory Sync are in public beta:

• Custom attribute mapping lets you sync additional user data from your IdP (such as department, employee_id, or cost_center) directly into publicMetadata on the Clerk user object. Attribute definitions are configured once at the enterprise connection level and shared across both your SSO connection (SAML or OIDC) and your Directory Sync connection, so the same attributes are available regardless of how a user authenticates or is provisioned. When Directory Sync is enabled, it becomes the exclusive source for those attribute values and they're read-only in Clerk until Directory Sync is disabled.

• Groups to role mapping lets you automatically assign Clerk roles based on IdP group membership. When a user is added to a group in your IdP, Clerk assigns the mapped role. When they're removed, they fall back to the next mapped role. If a user belongs to multiple groups with different role mappings, you can configure a precedence order to control which role takes effect.

Getting started

To enable Directory Sync, navigate to an enterprise connection in the Clerk Dashboard⁠, open the Directory Sync tab, and toggle it on. Clerk generates a SCIM base URL and bearer token to configure in your IdP.

Refer to the Directory Sync documentation for setup guides for Okta and Microsoft Entra ID, and the Custom Attribute Mapping documentation for details on the shared attribute pool.

Compatibility note

Our implementation follows the SCIM 2.0 protocol. However, your identity provider (and how you configure it) may not match our implementation completely. If you run into any compatibility issues, please report them to team-orgs@clerk.dev. We have a team standing by and will work to get compatibility resolved quickly.

Pricing

Directory Sync is included with your enterprise connection at no extra charge. Refer to the pricing page for connection pricing details.

You can now customize the look and feel of @clerk/expo's native components (<AuthView />, <UserButton />, <UserProfileView />) on both iOS and Android by pointing the @clerk/expo config plugin at a JSON theme file.

app.json

{
  "expo": {
    "plugins": [["@clerk/expo", { "theme": "./clerk-theme.json" }]]
  }
}

clerk-theme.json

{
  "colors": {
    "primary": "#6C47FF",
    "background": "#FFFFFF",
    "foreground": "#0F172A",
    "border": "#E2E8F0"
  },
  "darkColors": {
    "primary": "#8B6FFF",
    "background": "#0B0B0F",
    "foreground": "#FFFFFF"
  },
  "design": {
    "borderRadius": 12,
    "fontFamily": "Inter"
  }
}

The schema supports:

• colors — 15 semantic tokens (primary, background, input, danger, success, warning, foreground, mutedForeground, primaryForeground, inputForeground, neutral, border, ring, muted, shadow) as 6- or 8-digit hex strings.
• darkColors — same shape as colors, applied automatically when the device is in dark mode. Set "userInterfaceStyle": "automatic" in your app.json to let the system switch modes, or pin to "light" / "dark" to always use one palette.
• design.borderRadius — number, applied across components on both platforms.
• design.fontFamily — string, iOS only. The font must be bundled with your iOS app.

The JSON is validated at prebuild — invalid hex colors or value types fail the build with a clear error. iOS embeds the parsed theme in Info.plist; Android copies it to android/app/src/main/assets/clerk_theme.json. Both are picked up by the native SDKs automatically.

See the theming reference for the full schema and examples.

Browse more Overview data with infinite scrolling across user cohorts, organization cohorts, and waitlist tables.

The Overview page now includes infinite scrolling across all supported table variants, so you can keep exploring data without stopping to change pages.

This applies to the Users and Organizations views, along with the Waitlist mode overview, making it easier to browse large datasets in one continuous flow.

Open the Clerk Dashboard⁠ and scroll through the Overview tables to see the new experience.

The Overview page now includes a Filter test users setting for the Users view. User analytics previously showed combined regular and test user data. Now, when the toggle is enabled, test users are excluded from all Overview charts and metrics.

Test users are defined as having:

• +clerk_test in the email identifier
• +15555550100 as the phone

Open the Clerk Dashboard⁠ and use the Overview settings menu in the users view to try it.

Clerk Billing now has support for annual-only subscriptions. Previously, all plans renewed monthly with an option to subscribe on an annual basis. Now, you can configure plans to support annual-only billing.

To enable support for annual-only plans, visit your applications Updates page to opt-in to annual-only plans.

Important

Opting into annual-only plans will result in the fee property of plans potentially being null. Please ensure any logic your application has that interacts with the fee property is updated to account for null values.

To configure a plan for annual-only billing, enable only the "Annual base fee" option in the plan settings.

When customizing session tokens, you can now preview the resulting claims before saving your changes.

Select a user to generate claims based on the current template. This lets you verify that custom claims, template expressions, and organization data produce exactly the claims you expect.

Previously, saving a template then inspecting a real session token was required to check the template is correct. Preview lets you ensure expected behavior before impacting real users.

Restrict your end users from modifying their email address, phone number, or username after sign up.

You can now prevent end users from adding new or modifying existing email addresses, phone numbers, or usernames after they have signed up through the new Restrict changes toggle in the Clerk Dashboard. Navigate to the User & authentication⁠ page to enable.

Enabling this feature gives you the ability to have maximal control over the exact identifiers your end users can use to sign in to your application. If you'd like to control which identifiers are allowed at sign-up rather than locking them afterwards, see restrictions for allowlists, blocklists, and disposable email blocking.

With this setting enabled, your end users will still be able to view their identifiers in their User Profile, but will not be able to add, remove, or modify the respective identifier. For email addresses, this restriction extends to social connections: End users are prohibited from connecting an OAuth account that would otherwise add a new email address to their account.

Of course, you still have the ability to modify their end users' identifiers at any time on the Users page of the Clerk Dashboard⁠ or using our Backend API⁠.

If you would like to have support for restricting end users from changing other attributes than email address, phone number, or username, please reach out to us to share this feedback.

Starting today, membership limits on organizations can be granted directly by subscribing to a Clerk Billing plan, allowing organizations to purchase a higher membership limit in a self-serve fashion.

This makes it possible to target plans to organizations of specific size. For example, you may let organizations use your most affordable plan for up to ten seats, but require them to upgrade to a more expensive plan to get unlimited seats.

Seat limits are enforced automatically through the integration of Clerk's Billing and B2B Authentication products. When an organization hits its seat limit, Clerk will prevent adding additional members and guide users toward upgrading.

More seat-based features to come

This release is our first step towards seat-based billing for Clerk Billing. We know that many use cases require organizations to be able to purchase a specific number of seats specified at checkout at a per-seat cost; we hope to have more to say on that functionality in the near future. We're excited to ship this first step into seat-based billing and to expand on it.

How to create a seat-limited plan

• Navigate to the New Organization plan⁠ page in your instance's settings.
• Toggle on the Seat-based section.
• If you'd like the plan to convey an unlimited number of seats, leave Unlimited members selected. (You need to have the B2B Authentication add-on to select this option.)
• If you'd like to set a limit, select Custom limit and enter the limit.

The Overview page now has a dedicated waitlist view so it's easier to understand sign-up access and recent waitlist activity.

Read more

The Overview page now has a dedicated waitlist view so it's easier to understand sign-up access and recent waitlist activity.Read more

Add authentication and user management to your app through Stripe Projects with a CLI-based workflow for teams and AI agents.Read more

Visualize how active each organization is in your applicationRead more