Versioning

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.

A complete list of all the available versions with their changes can be found on the API versions page.

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 three options to specify the version:

Query parameter: Set the __clerk_api_version query parameter in your request URL.
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.

Last updated on March 12, 2024