Supabase Introduces Auth Asymmetric JWTs and API Keys Breaking Changes

Asymmetric JWTs in Q4 2024

In the beginning of October 2024 Supabase has announced the details on upcomming introduction of asymetric JWTs.

The news is that Supabse has decided to push back the launch from 7th October 2024 to Q4 2024 to roll this out meticulously; they want to perform exhaustive security checks and spend more time dogfooding internally.

Very simply speaking this is good old days public - private keys encription flow. Your one private key used in a backend and publicly shareable key to read.

Asymmetric JWTs in Supabase are long awaited feature as they should also help to get rid of the infamous getUser() warning logs long lasting annoyance.

Changes

To use asymetric JWTs in your Supabase project you will need to include these following changes:

• Get an asymmetric key through the Supabase dashboard.
• Include new public JWKs endpoint for retrieving the public JWK to verify JWTs. This will be exposed through the https://<project_ref>.supabase.co/auth/v1/.well-known/jwks.json endpoint. The symmetric secret will not be exposed through this endpoint for security reasons.
• Use a new method called getClaims which handles verifying the JWT and returning the claims in it.
• Use the public key in matter, you will be able to download the public keys in different formats through the dashboard (e.g. PEM, JWKs).
• Ensure that you are using the new API keys (publishable key: sb_publishable_123abc and secret key: sb_secret_123abc instead of old anon key: eyJhbGciOiJIUzI1...FDsBGn0iqSmL28Zeg8f0 and old service_role key: eyJhbGciOiJIUzI1...SEVEyZQNhffCoSj4P5A).
• Update all your clients to use at least supabase-js version x.x.x (the version number will be updated closer to the release date) which will inroduce the new getClaims method.

getClaims Method

The new getClaims method will be able to handle verifying both asymmetric JWTs as well as symmetric JWTs.

To use getClaims() to verify the JWT your code would have to look something like this:

import { createClient } from 'supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

// previously, using getUser() requires making an 
// additional network request to Supabase Auth to verify the JWT
// 
// const { data, error } = await supabase.auth.getUser()

// getClaims() will always return the JWT payload if the JWT is verified
// If it's an asymmetric JWT, getClaims() will verify using the JWKs endpoint.
// If it's a symmetric JWT, getClaims() calls getUser() to verify the JWT. 
const { data, error } = await supabase.auth.getClaims(jwks)

Using getClaims(jwks) with JWKs will avoid a network request completely.

Calling getClaims() without passing in the JWKs will still require the network request to the /auth/v1/.well-known/jwks.json endpoint however Supabase will be able to cache the JWKs in-memory so that subsequent calls to getClaims() don't have to make another requests.

Advantages

• Usage of asymmetric key cryptography rather than a shared symmetric secret. Since asymmetric keys don’t use a shared secret, there is less risk of the secret being leaked.
• Reducing extra network requests due to faster JWT verification times since there’s no need to make a network call to Supabase Auth via getUser().
• Zero-downtime key rotation. Public keys can be exposed and any one of them may be used for verification.

Migration

New projects that are created after 1st May 2025 will be created with an RSA asymmetric key by default. Existing projects can choose to start using asymmetric keys as mentioned above.

After the JWT expiry period, you can safely revoke the “Previously Used” symmetric JWT since new JWTs will now be signed with the asymmetric key.

Current Supabase API keys (anon key and service_role key) in your existing projects will continue to work until 1st October 2025. By that time these legacy API keys will be deleted and removed from the Docs / Dashboard and you have to migrate to use the new API keys or your app will break.

More Information

You can read more in these Supabase Github discussions Supabase Auth: Asymmetric Keys support in Q4 2024 #29289 and Changes to Supabase API Keys in Q4 2024 (new & restored projects affected from 1st May 2025, no breaking changes for existing projects until 1st October 2025) #29260.