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)

[kangmingtay]

Introduction

We’re changing the way API keys work in Supabase to improve your project’s security and developer experience and plan to roll out these changes Q4 2024. Rest assured that the current API keys in your existing projects will continue to work for another year until 1st October 2025 during the transition.

We’ll contact you when we launch the new API keys, and when we do, no immediate action is required. However, we strongly recommend that you migrate your project’s existing API keys for the new set when they are introduced. Updating to use the new API keys is a quick and painless process and can be as simple as a change in environment variable and take just a few minutes.

Timeline

Update (2nd October 2024): We have decided to push back the launch from 7th October 2024 to Q4 2024 to roll this out meticulously; we want to perform exhaustive security checks and spend more time dogfooding internally.

Key Dates	Description	User Action Needed
Q4 2024 7th October 2024	Introduction of new API keys. New projects will automatically generate both new API keys and legacy API keys to help ease the transition. Existing projects can continue to use the legacy API keys and can opt in to use the new API keys by manually generating them.	No immediate action needed. We strongly recommend that you migrate to use the new API keys.
1st May 2025	We will start sending you monthly reminders to migrate off legacy API keys and start using the new keys. New projects will be created with only new API keys. Projects restored from 1st May 2025 will no longer be restored with the legacy API keys.	You are highly encouraged to migrate off to use the new API keys before this date since paused projects that are restored risk being broken as they won’t have the legacy keys.
1st October 2025	Legacy API keys will be deleted and removed from the Docs / Dashboard.	You have to migrate to use the new API keys by this point or your app will break.

Why are we doing this?

Currently there is a tight coupling between API keys and the JWT secret which presents a few challenges:

1. Difficult to revoke the service_role or anon key. Imagine if someone in your Supabase organization leaves the team, and you want to roll your project’s JWT secret to revoke their access? Or you accidentally commit the service_role key into your version control system and need to roll it?

   If either of these keys gets leaked, the developer’s only option is to roll the JWT secret by generating a new one. When the JWT secret is rolled, all authenticated users would be logged out, clients using the older anon and service keys would break. Realistically, there is no way to roll the JWT secret without downtime.

2. Sub-optimal developer experience to create an API key with a custom role. Developer needs to sign a JWT with a long expiry time and their custom role using the secret.

The introduction of new API keys solves the above problems by allowing the developer to:

• roll individual API keys
• roll the API keys without logging out their users
• create custom API keys easily

API Key changes

These are the planned changes for the API keys:

• anon key will be renamed to publishable key and the service_role key will be renamed to secret key. publishable api keys are meant to be used along with Supabase Auth users and secret api keys are for use from the server side and bypasses all row level security policies. We chose to use publishable and secret to align with stripe’s terminology and preferred it to terms like public and private since those could be confused with public / private key cryptography when we introduce asymmetric JWTs to Supabase Auth.

• New API keys will look like regular strings instead of JWTs:

  Legacy API Keys	Equivalent New API Keys
  anon key: eyJhbGciOiJIUzI1...FDsBGn0iqSmL28Zeg8f0	publishable key: sb_publishable_123abc
  service_role key: eyJhbGciOiJIUzI1...SEVEyZQNhffCoSj4P5A	secret key: sb_secret_123abc

• With the new API keys, it will be possible to revoke individual API keys and without revoking the JWT secret. Once the legacy API key is revoked, it won’t be possible to restore them.

• New projects will be created with both new and legacy API keys until 1st May 2025. New projects created after this date will only be created with new API keys.

• Projects that are restored after 1st May 2025 will not be restored with legacy API keys.

• Legacy API keys will no longer work for all projects after 1st October 2025.

Migration to the new API keys

1. If you want to use the new API keys, all you need to do is to swap out your keys for the new ones:

Legacy API Keys	Equivalent New API Keys
anon key	publishable key
service_role key	secret key

2. Update your .env file to contain the new API key

# the legacy anon key
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...w6PYobnC7Ep7EnDd9DG25qBFDsBGn0iqSmL28Zeg8f0 

# the new publishable key
SUPABASE_PUBLISHABLE_KEY=sb_publishable_123abc

3. Instantiate the supabase client with the new API Keys.

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

const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY)

4. After all your clients have been instantiated with the new API keys, you can revoke the legacy keys from the dashboard.

Frequently Asked Questions

• What is the timeline for the migration?
  • See "Timeline" section above
• My app is deployed through Vercel / Netlify, how do I use the new API keys?
  • If you’re using Vercel or Netlify, changing the keys in your environment will only be reflected when you trigger a new deployment.
• I only connect to the database via the connection string — do I need to worry about this at all?
  • No, unless you use the supabase client libraries to make queries to the database.
• How do we do custom claims?
  • Currently, users have to manually create a new key with their custom claims using the JWT secret provided.
  • There will be support for creating new API keys with custom properties in the dashboard and management API.
• What benefit do we get from migrating to use the new API keys?
  • You can revoke an individual key in the event of a compromise
  • You can revoke keys without logging out existing users
  • You don’t have to deal with minting a new JWT using the JWT secret if you want to add custom claims to an API key.
• What is the interaction between the apikey header, the Authorization header and the underlying Postgres role used?
  • The new API keys are just regular strings instead of JWTs.
  • By default, secret API keys assume the service_role. When creating the new secret API keys, you can override this behavior and assign a custom role. Downstream services like postgREST and storage assume this role when they are called with this API key.
  • By default, publishable API keys default to the anon role. When a user JWT is passed in via the Authorization header, the role claim in the JWT is used instead. You cannot map publishable keys to custom roles when creating the key, like you will be able to do with secret API keys.