What is Auth v2?

We're releasing a new authentication strategy which enables networkless authentication and supports more application architectures.

We have been using Auth v2 on www.clerk.dev for the past month and are excited to extend the beta to our customers.

Please give it a try and let us know if you run into any trouble!

Key Benefits

• Authenticating users from your backend no longer requires the network. Users are now authenticated with a short-lived JWT (1 minute). The JWT is automatically refreshed by Clerk's javascript.
• If your frontend is on a different subdomain from your backend, authentication data is now conveyed over the industry-standard Authorization header. This replaces using {credentials: "include"} with the Access-Control-Allow-Credentials CORS header.
• Auth v2 is compatible with applications that are rendered server-side. We have support for Rails at launch, and will add support for React SSR next.

How Auth v2 works

In Auth v1, your application's backend receives a long-lived token and verifies it "just-in-time" against Clerk's Backend API.

In Auth v2, we have transitioned to a "pre-authentication" model. A short-lived JWT is retrieved from Clerk's Frontend API before a request is made to your application's backend. Then, Clerk's SDK simply decodes and verifies this token to determine the authenticated user.

To ensure a valid JWT is always available, Clerk.js automatically refreshes the token in the background. From there, your application's architecture determines how the token is sent:

• If your backend is same-origin to your frontend, the token resides in a cookie named __session which is automatically sent with requests.
• If your backend is cross-origin to your frontend, you must manually send the token in the Authorization header as a Bearer token.

Migrating to Auth v2

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

<aside> ⚠️ You're among the first switching to this new architecture and you may encounter some rough edges. We're happy to schedule a time to assist with the migration in real time, and we're also available in our traditional support channels.

</aside>

React application with same-origin backend

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