Versioning overview

When backwards incompatible changes are necessary for an API, new versions are released to prevent disruption to existing applications. These versions are identified by their release date, such as 2021-02-05. Both the frontend and backend APIs follow the same version.

How Clerk SDKs are versioned and released

Clerk is on roughly a 6 month major release cycle for its SDKs. This means that every ~6 months, there is a release cycle across all SDKs that may include breaking changes that need to be released for any given SDK. All of our SDKs use semantic versioning⁠ independently.

You may see the term "Core N" in our docs and release announcements. This refers to a set of core functionality that is included across all SDK libraries, rather than to a specific version of any individual SDK. As an example, in the Core 2 release, the Next.js SDK changed its major version from v4 to v5. However, not every SDK had a major version increment as part of the Core 2 release.

When there is a new Core release, you can expect an upgrade guide alongside it for each Clerk SDK, and that guide will mention the SDK's current semver version. However, this is not generally something that anyone needs to be concerned with - if you want the latest version, you can just install the SDK as usual and get the latest version. The "Core N" terminology is simply a way for us at Clerk to broadly refer to a set of changes and improvements made to Clerk's functionality that is included in all of our SDKs to different extents. There is no literal SDK or Clerk library called "Core".

Whenever a new Core release is cut, the latest version of each SDK including the previous Core release will be tagged in npm, to make it simple to roll back if needed. So, for example, if Clerk released Core 2:

• npm i @clerk/nextjs would install v5, which would be on top of Core 2.
• npm i @clerk/nextjs@latest-v4 would install v4, which would be on top of Core 1.

What constitutes a breaking change

A breaking change is any modification that would require users to alter their existing setups. These include:

• Change in property type: Altering the data type of a property in either requests or responses.
• Removal of a property: Deleting a property or parameter from a request or response.
• Change in property name: Renaming a property in request or response payloads.
• Backwards incompatible endpoint changes: Implementing changes in an endpoint's functionality that older client versions cannot support. For instance, adding a new status to the sign-in process.
• Endpoint removal: Discontinuing access to an existing endpoint, which remains accessible in earlier versions.

When using an SDK

Each Clerk SDK version corresponds to a specific API version, so by updating the SDK, you're also updating to the latest compatible API version.

Choosing an API version

When making direct API calls to an endpoint, there are two options to specify the version:

1. Query parameter: Set the __clerk_api_version query parameter in your request URL.
2. Clerk-API-Version header: Include a Clerk-API-Version header in your requests.

Available versions

2025-04-10

Adds support for version 2 of Clerk session tokens. The following SDKs are compatible with this version:

2024-10-01

• Notification for new sign-ins to users' accounts feature becomes available.
• The response for sign-ins with an email address that matches a SAML connection is updated:
  • Instead of responding with a status of needs_identifier, the API now returns a status of needs_first_factor.
  • The email address that matched will be returned in the identifier field.
  • The only strategy that will be included in supported first factors is enterprise_sso.

2021-02-05

The initial API version was released on 2021-02-05 as part of the first Clerk release. It predates the versioning system. All changes made to it since then are backwards compatible.

Long term support policy

This section explains the support plans for major versions of Clerk's SDKs. When a new major version of an official Clerk SDK is released, the previous version is placed into long term support (LTS) mode for a period of one year. During this period, new features and bugfixes will not be actively backported, however, any critical patches will be actively backported.

After the LTS period ends, there will be no further changes to the code for that version in any form, and we will strongly recommend upgrading to a new version for product and security improvements. While we strongly recommend upgrading to keep your application secure, all previous versions of SDKs will continue to function indefinitely even if not upgraded.

Schedule

Library compatibility

Clerk's SDKs run in the browser, in Node.js (+ other compatible runtimes), or in both. Below you can find out which Node.js and browser versions Clerk's SDKs support.

Terminology

• Critical Patch - A critical patch addresses an issue that prevents an SDK from delivering intended user value under typical conditions. Other items, such as minor bug fixes and new features are not considered "critical patches".

• Active - Receives priority attention from the core maintainers of Clerk. New features to Clerk are only available in the Active version.

• Long term support - Receives critical patches, but does not receive new features.

• Unsupported - This version of Clerk no longer receives official support of any kind.

• Evergreen browser - Includes these browsers: Google Chrome, Mozilla Firefox, Microsoft Edge (Chromium), Safari, Opera. No support for Internet Explorer (IE).