# 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](https://semver.org/) 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 3:

- `npm i @clerk/nextjs@latest` would install v7, which would be on top of Core 3.
- `npm i @clerk/nextjs@latest-v6` would install v6, which would be on top of Core 2.

## 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.

> You must choose only one method to specify a version. Using both the query parameter and the header simultaneously will lead to an invalid request.
> The same is also true when the version is invalid.

## API versions

### 2025-11-10

Brings more consistency and clarity to the Clerk Billing API endpoints. See the [migration guide](https://clerk.com/docs/guides/development/upgrading/upgrade-guides/2025-11-10.md) for more details.

The following SDKs are compatible with this version:

| SDK                  | Version                                       |
| -------------------- | --------------------------------------------- |
| Next.js              | @clerk/nextjs v6.35.0 or higher               |
| React                | @clerk/react v5.54.0 or higher                |
| JavaScript           | @clerk/clerk-js v5.107.0 or higher            |
| Expo                 | @clerk/expo v2.19.0 or higher                 |
| TanStack React Start | @clerk/tanstack-react-start v0.27.0 or higher |
| React Router         | @clerk/react-router v2.2.0 or higher          |
| Express              | @clerk/express v1.7.48 or higher              |
| Astro                | @clerk/astro v2.15.0 or higher                |
| C#                   | Clerk.BackendAPI v0.14.0 or higher            |
| Chrome Extension     | @clerk/chrome-extension v2.8.0 or higher      |
| Fastify              | @clerk/fastify v2.6.0 or higher               |
| Go                   | clerk-sdk-go v2.5.0 or higher                 |
| Java                 | com.clerk:backend-api v4.0.0 or higher        |
| JavaScript Backend   | @clerk/backend v2.21.0 or higher              |
| Nuxt.js              | @clerk/nuxt v1.12.0 or higher                 |
| PHP                  | clerkinc/backend-php v0.4.0 or higher         |
| Python               | clerk\_backend\_api v4.0.0 or higher          |
| Remix                | @clerk/remix v4.13.15 or higher               |
| Vue                  | @clerk/vue v1.15.0 or higher                  |

### 2025-04-10

Adds support for [version 2 of Clerk session tokens](https://clerk.com/docs/guides/sessions/session-tokens.md).
The following SDKs are compatible with this version:

| SDK                  | Version                                       |
| -------------------- | --------------------------------------------- |
| Next.js              | @clerk/nextjs v6.15.0 or higher               |
| React                | @clerk/clerk-react v5.28.0 or higher          |
| JavaScript           | @clerk/clerk-js v5.61.0 or higher             |
| Expo                 | @clerk/expo v2.9.12 or higher                 |
| TanStack React Start | @clerk/tanstack-react-start v0.13.5 or higher |
| React Router         | @clerk/react-router v1.2.5 or higher          |
| Express              | @clerk/express v1.4.5 or higher               |
| Astro                | @clerk/astro v2.6.4 or higher                 |
| C#                   | Clerk.BackendAPI v0.2.1 or higher             |
| Chrome Extension     | @clerk/chrome-extension v2.2.29 or higher     |
| Fastify              | @clerk/fastify v2.2.5 or higher               |
| Go                   | clerk-sdk-go v2.3.1 or higher                 |
| Java                 | com.clerk:backend-api v3.0.0 or higher        |
| JavaScript Backend   | @clerk/backend v1.28.0 or higher              |
| Nuxt.js              | @clerk/nuxt v1.5.5 or higher                  |
| PHP                  | clerkinc/backend-php v0.1.6 or higher         |
| Python               | clerk\_backend\_api v2.2.0 or higher          |
| Remix                | @clerk/remix v4.5.17 or higher                |
| Ruby                 | clerk-sdk-ruby v4.1.0 or higher               |
| Vue                  | @clerk/vue v1.6.1 or higher                   |

### 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

> Future time ranges are listed when a specific target date is not yet determined. The version "Core `N`" refers to [how Clerk SDKs are versioned and released](https://clerk.com/docs/guides/development/upgrading/versioning.md).

| Version     | Status            | As Of        | Until        |
| ----------- | ----------------- | ------------ | ------------ |
| Core 3      | Active            | January 2026 | TBD          |
| Core 2      | Long term support | January 2026 | January 2027 |
| Core 1      | Unsupported       | -            | -            |
| Legacy (v3) | Unsupported       | -            | -            |

### 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.

| Version | Node.js     | Browsers                                       |
| ------- | ----------- | ---------------------------------------------- |
| Core 3  | `>=20.9.0`  | Browsers released in the last two years        |
| Core 2  | `>=18.17.0` | Browsers released in the last two years        |
| Core 1  | `>=14.0.0`  | Chrome 114, Edge 115, Firefox 116, Safari 12.1 |

### 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).

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)