Clerk Changelog

A SAML IdP signs every SSO response with a private key, and Clerk verifies it with the certificate stored on the enterprise connection. Until now, a connection held only one certificate, so a key rotation meant replacing it at exactly the moment the IdP switched: upload the new certificate too early, and sign-ins would fail while the IdP still used the old key; upload it too late, and they would fail once the IdP started using the new key.

A SAML enterprise connection now trusts up to five signing certificates at once. Add the IdP's next certificate ahead of time, let the IdP switch whenever it does, and remove the old certificate afterward. No sign-in is rejected on either side of the switch.

How it works

Changing a connection's certificates replaces the entire list with the certificates you provide. If an update doesn't include certificates, the list stays the same. That's also how you stop trusting a leaked key: remove it from the list. Uploads take a single certificate or a PEM bundle, which many IdPs export when they list more than one signing key; every certificate in the bundle becomes an entry. Each certificate shows its expiry, with a warning when it expires within 30 days.

Where to manage certificates

• Clerk Dashboard: the Certificates list on a SAML connection's SSO tab shows every trusted certificate with its expiry and lets you add one from a file (a PEM bundle adds several) or remove one.
• Organization admins: the Security tab of <OrganizationProfile /> and the self-serve SSO setup show the same list for their Organization's connection, with the same upload and remove actions.
• Backend API: pass the full list as idp_certificates when you create⁠ or update⁠ an enterprise connection; responses include each certificate with its validity window. The single idp_certificate field keeps working, accepts a PEM bundle, and is deprecated.

Get started

Multiple certificates are available on every instance with SAML enterprise connections; existing connections keep their current certificate as the only entry until you add more. Read the certificate rotation guide for the step-by-step rotation and the API details.

Directory Sync provisions, updates, and deprovisions an Organization's members as its identity provider changes. Until now, your team configured it in the Clerk Dashboard and handed a SCIM endpoint and bearer token to each customer's IT admin. Self-serve Directory Sync moves that setup into the Security tab of <OrganizationProfile />, next to self-serve SSO, so the admin who configured the SSO connection can finish provisioning without Dashboard access.

How it works

When self-serve SSO is enabled for an Organization, a Directory Sync section appears beneath the SSO section in that Organization's Security tab. An admin with the org:sys_entconns:manage permission opens a three-step wizard. Clerk picks the directory provider from the SSO connection, so Okta Workforce, Microsoft Entra ID, Google Workspace, and custom SAML or OIDC connections each get the matching setup.

• Configure: For most identity providers, Clerk generates a SCIM endpoint URL and bearer token, along with setup instructions for that IdP. For Google Workspace, Clerk reads the directory through Google's Admin SDK. The admin uploads a service account key and enters the email address of a Workspace admin account for Clerk to act as.
• Review attributes: The standard mappings Clerk applies are listed, so the admin knows what will be stored.
• Test provisioning: The admin assigns a test user in their IdP and watches it appear. For Google Workspace, they can trigger a sync and see the result of the last run.

Provisioning works before the SSO connection is active, so an admin can populate the Organization's membership first and turn on SSO when they're ready. After setup, the admin can pause, resume, or remove the directory from the same section.

What your team sees

In the Clerk Dashboard, a self-serve directory looks like any other directory. You still control Custom attribute mapping and Role mapping, and Role mapping is off by default for self-serve directories..

Get started

In the Clerk Dashboard⁠, select an Organization, open its Settings, and turn on Allow this organization to set up enterprise SSO and Directory Sync under Organization permissions. The Security tab then surfaces wherever your app renders <OrganizationProfile />, including through <OrganizationSwitcher />.

For setup details and requirements, refer to the self-serve Directory Sync documentation.

An active enterprise single sign-on (SSO) connection requires users on its domains to sign in through an identity provider (IdP). If the IdP goes down or the connection breaks because a certificate expires or a setting changes, those users can't sign in, including the people who need to fix the connection.

SSO bypass lets users on an allowlist sign in with a one-time email code instead of using the IdP. Everyone else must continue to use SSO.

How it works

Add users to a connection's allowlist. When one of them enters their email address, <SignIn /> shows a Can't use SSO? link next to the SSO option. After confirming they want to continue without SSO, they get a code by email and sign in with an ordinary session. Users who aren't on the allowlist don't see the link.

You can only add users with a verified email address on a domain the connection serves. Clerk doesn't check whether the address still exists in your IdP. Clerk records each successful bypass as a sign_in.sso_bypass.succeeded event in Application Logs.

Who manages the allowlist

• You can manage the allowlist from the connection's page in the Clerk Dashboard⁠ or with the Backend API⁠. Both options work whether or not your application uses Organizations.
• Organization members with the org:sys_entconns_sso_bypass:manage system permission can manage their Organization's allowlist from the Security tab of <OrganizationProfile />. The default Admin role includes this permission. They can add one member or all members with a given role.

Get started

SSO bypass is available on every instance with enterprise connections. To use it, enable Email verification code sign-in and add users to an allowlist. Read the SSO bypass guide to learn more, including how to support it in a custom sign-in flow.

An Organization can now have more than one enterprise connection. Previously, creating a second SAML or OIDC connection for an Organization that already had one failed with organization_already_has_sso_connection. That limit is gone across the Clerk Dashboard⁠ and the Backend API⁠.

Why this matters

Some enterprise customers use more than one identity provider (IdP). This happens after an acquisition, during a migration from one IdP to another, or when subsidiaries and contractors sign in through separate providers. Before, each connection needed its own Organization. Now every connection can point to the same Organization, each with its own domain, protocol, and settings.

Directory Sync follows

Because each enterprise connection can have its own Directory Sync, a single Organization can now be fed by several directories, and the same person can be managed by more than one of them.

Clerk tracks each directory's view of a user separately:

• A user stays active while at least one enabled directory reports them as active. Clerk deactivates the user and revokes their sessions only when every enabled directory that manages them has deprovisioned them.
• Organization membership and Role mapping follow the directories that still grant access. Deprovisioning from one directory withdraws only that directory's grant. The membership is deleted only when no directory grants it anymore.
• Disabling or deleting a directory withdraws the memberships it granted without waiting for the IdP to sync. The recalculation runs in the background. Each affected user's status is recalculated from the remaining enabled directories: they are deactivated only if every one of those has deprovisioned them, and if none remain their status doesn't change.

Get started

In the Clerk Dashboard, navigate to the SSO connections⁠ page and add a connection for an Organization that already has one. Read the Organization-level Enterprise SSO and Directory Sync docs to learn more.

Client ID Metadata Documents⁠ (CIMD) are now generally available for all Clerk applications.

A compatible client uses an HTTPS URL as its client_id. Clerk fetches the metadata document at that URL and validates the client's identity and redirect URIs. This gives MCP and other public OAuth clients a stable identity without a pre-issued client ID, client secret, or Dynamic Client Registration.

What's changed since the beta

• Available everywhere. CIMD settings now appear on the OAuth applications⁠ settings page for every application.
• Off by default. Nothing changes for your existing OAuth flows until you enable Publish CIMD support.
• Same admission controls. Explicitly allow clients by Client ID URL, choose their scopes, review implicitly allowed clients, and set Client admission to Pre-registered clients only to restrict flows to clients you've reviewed.

Get started

1. In the Clerk Dashboard, navigate to the OAuth applications settings⁠ page.
2. Under Client onboarding, enable Publish CIMD support to publish CIMD in your authorization server metadata.
3. Optionally, set Client admission to Pre-registered clients only and add the clients you trust from the Applications tab.

Read Manage OAuth clients with Client ID Metadata Documents for the full guide, including metadata requirements, PKCE, and client admission policies.

Application Logs⁠ now record delivery events for SMS messages sent by Clerk, including phone verification codes, OTPs, and password reset codes. When a user reports a missing code, these events show whether the message was accepted, delivered, rejected, or left unconfirmed.

The delivery lifecycle

Each message can generate several event types, helping you distinguish between a send failure, a delivery rejection, and an unknown outcome:

• sms.accepted — the delivery provider accepted the message (not yet proof it reached the phone)
• sms.delivered — the carrier confirmed delivery to the handset
• sms.failed — the send stopped before handoff, or the provider rejected it
• sms.undeliverable — the carrier could not deliver it after accepting it
• sms.unconfirmed — the provider reported an unknown delivery outcome

Failure events carry a normalized reason — like invalid_phone_number, destination_unreachable, or rate_limited — so a failure tells you whether to fix the number, wait out a provider limit, or adjust your own configuration. The message body, verification code, and provider identity are never included.

Filtering and search

The dedicated SMS logs view⁠ lists these events, where you can filter by a single event type like sms.failed or by the destination phone number to pull up one recipient's history. Every event for a single message shares a trace, so you can follow its whole timeline end to end.

Get started

SMS events are available on all plans as part of Application Logs. Retention varies by plan. See the pricing page for details. Open the SMS logs view⁠ to investigate SMS delivery, or Application Logs⁠ to view SMS events alongside other application events. Read the documentation to learn more.

Going forward

SMS delivery events build on Clerk's ongoing observability work alongside Admin Logs and Email Logs.