Auth v2

Introduction

Auth v2 is the new authentication scheme which brings many improvements and opens the possibilities for using Clerk with new application architectures. It is a major overhaul of the inner workings of Clerk.

In this page we'll provide a high-level overview of Auth v2 and how it differs from its predecessor, Auth v1.

How Auth v1 works

In Auth v1, authentication is conveyed using a long-lived token that's generated by our Frontend API, when a user signs in/signs up to your application.

This token is a JWT and it is persisted in a browser cookie. The cookie then travels along with requests issued by Clerk.js from the user's browser to the Clerk Frontend API (e.g. clerk.yourapp.com). By reading this cookie, the Frontend API can determine whether the user is signed in to your application and act accordingly.

Additionally, the same token is delivered via a cookie to your backend (e.g. www.yourapp.com), so that your application can also tell whether the current user is signed in to your application.

Critically, the primary source of truth - the one who knows whether a user is signed in or not, is the Frontend API.

Shortcomings

There are certain shortcomings that stem from the design of Auth v1.

In cross-origin architectures, there's typically a frontend living in a different domain than the backend API. An example is a React frontend at [www.example.com](<http://www.example.com>) using an API at api.example.com. In Auth v1 one has to configure Access-Control-Allow-Credentials & Access-Control-Allow-Headers in their backend, and credentials: include in their frontend XHRs.
Auth v1 does not support cross-site architectures. For example, an application with a frontend at www.example.com and its backend at foo.bar.com cannot use Clerk in Auth v1 mode. This limitation is due to the fact that browsers implement a number of storage access policies with regards to cookies in third-party contexts, for security and privacy purposes.
Auth v1 does not support server-rendered applications in which the backend needs to know the state of the user (i.e. signed in or not) prior to generating the response. A typical example of this is a Rails application that redirects to a different page if the user is signed in, using a before_action filter. This limitation is due to the fact that in such cases, client-side JavaScript doesn't have the chance to run before the server-side code that renders the response, and so Clerk.js hasn't yet set the appropriate cookie for the backend to pick it up.
Since the token is long-lived, in server-rendered applications an additional request to the Clerk API is needed, to validate that the token is still valid. This incurs additional latency to end users.

Fortunately, Auth v2 effectively tackles the aforementioned issues, with a completely redesigned authentication scheme.

How Auth v2 works

In Auth v2, requests from Clerk.js to the Clerk Frontend API (e.g. clerk.yourapp.com) continue to work with long-lived tokens, as was the case in v1.

However, there's one critical change: your application (e.g. www.yourapp.com), instead of the long-lived token, will now receive a short-livedsession token. This token is a JWT with a 1-minute lifetime, that's generated via Clerk.js from the Frontend API and represents an authenticated session of a particular user.

A sample of the token claims follows:

{
  "exp": 1633683221, // token expiration timestamp (1 minute)
  "iat": 1633683161, // token issuance timestamp
  "nbf": 1633683151,
  "sid": "sess_1ytvQxMxwO2CSNm314dlJitz6Hr", // the session's id
  "sub": "user_1yUZ919oruYxkUqot0NathzN9jt"  // the user's id
}

This token is still persisted in a cookie, but this cookie is now accessible by JavaScript code; hence the short lifetime, in order to mitigate against XSS attacks.

Since the token is short-lived, Clerk.js automatically refreshes it by polling the Frontend API in the background, so that your backend is guaranteed to always receives a fresh token by the user's browser.

How the token travels to your backend depends on the architecture of your application. Briefly put, in same-origin architectures the token resides in the __session cookie, which is managed automatically by Clerk.js. In cross-origin architectures, the token has to be put in the Authorization header manually by you, the developer.

New versions of our SDKs exist that support Auth v2 and are therefore able to verify the new session token.

Benefits compared to Auth v1

Auth v2 brings some important benefits compared to Auth v1.

Developers of cross-origin architectures no longer have to configure their backend with Access-Control-Allow-Credentials and their frontend with credentials: include. Instead, they merely have to include the Authorization: <token> header in their XHRs, which is much more intuitive and simple as a change.
Developers of cross-site architectures can finally use Clerk too! An application with a frontend at www.example.com and an API at foo.bar.com can leverage Clerk's first-in-class authentication and user management.
Server-rendered applications can now effectively act based on whether the user is signed in or not. This is achieved via an intermediate page that our SDKs render on such occasions, that takes care of synchronizing the local __session cookie with the state of the Frontend API. After this happens, the page will redirect back to the original location.
Since a fresh token will be received every time with a request to your application, with a 1-minute lifetime, there's no strict requirement to perform additional requests to validate the token - it's already validated by the SDK. (However, if you still want to validate it, you can do so.)

In conclusion, more use cases are supported, less configuration is needed and better performance is achieved with Auth v2.

Using Auth v2

Auth v2 is available today for use in JavaScript, Ruby and Go applications, whether they're client-rendered or server-rendered.

Our SDKs have also been updated accordingly, with support for Auth v2. In the next sections you can find more details about each of them.

If you created your application from the Dashboard after 22 Oct 2021, it's already using Auth v2.

If you created your application from the Dashboard prior to 22 Oct 2021 and you wish to upgrade to Auth v2, or if you're not sure whether your application is Auth v1 or Auth v2, please reach out to us via the communication channels mentioned in the last section.

1
Make sure you use clerk-sdk-node version 2.1.0 or later.
2
Note: Server-side rendering is only supported for Next.js applications at this point.

1
Make sure you use clerk-sdk-ruby version 2.0.4 or later.

1
Make sure you use clerk-sdk-go version 1.1.3 or later.
2
That version provides the WithSessionV2 and RequireSessionV2 middlewares.

Upgrading from Auth v1

Depending on the architecture of your application, different steps are needed in order to upgrade to Auth v2.

If you created your application after 22 Oct 2021, it's already using Auth v2.

React application with same-origin backend

Example: A Next.js app leveraging the /api folder

Bump @clerk/clerk-sdk-node in your backend to v2.1.2 or later
Bump @clerk/clerk-react in your frontend to v2.2.1 or later
Verify everything is working in your development instance
Deploy to production
Your application is now running on Auth v2.
Contact us - we'll make one last change to your instance to stop setting a cookie on your application's backend.

React application with cross-origin backend

Example: React frontend at www.example.com, Node backend at api.foo.com

Bump @clerk/clerk-sdk-node in your backend to v2.1.2 or later
Verify everything is working in your development instance
Deploy to production
Bump @clerk/clerk-react to v2.2.1 or later
Update your frontend-to-backend requests to include the short-lived JWT in the Authorization header. The JWT can be retrieved with the getToken method on the useSession hook: const { getToken } = useSession();
Verify everything is working in your development instance, then deploy your frontend to production
Your application is now running on Auth v2.
Contact us - we'll make one last change to your instance to stop setting a cookie on your application's backend.

Server-rendered Ruby applications

Example: a traditional Rails application

Bump the Ruby SDK to v2.0.4
Bump @clerk/clerk-react to v2.2.1 or later
Verify everything is working in your development instance, then deploy
Contact us - we'll make one last change to your instance to stop setting a cookie on your application's backend.

If you encountered any issues or need assistance, please reach out to us via the communication channels mentioned in the last section.

Talk to us

We encourage you to try the new authentication scheme out!

We are more than happy to assist you in migrating your application to Auth v2 and we encourage you to do so.

Your feedback is extremely important to us - please reach out via the following communication channels, in case you have questions, suggestions or issues.