From e4f824b8356352965e9495aa42b0870241b472c2 Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Thu, 4 Jun 2026 11:56:23 +0200 Subject: [PATCH] docs: Strengthen keys note (#46578) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Summary by CodeRabbit * **Documentation** * Consolidated API key deprecation guidance into a reusable notice for consistent messaging across docs. Announces deprecation of legacy anon/service_role JWT-secret keys by end of 2026, instructs switching to sb_publishable_xxx / sb_secret_xxx, and provides steps to locate and copy both new and legacy keys. Applied across auth, getting-started, API, and realtime guides. --------- Co-authored-by: fadymak --- .../NavigationMenu/NavigationMenu.constants.ts | 2 +- .../content/_partials/api_keys_deprecation.mdx | 12 ++++++++++++ apps/docs/content/_partials/api_settings.mdx | 14 ++------------ apps/docs/content/_partials/api_settings_steps.mdx | 14 ++------------ apps/docs/content/guides/api/creating-routes.mdx | 11 +---------- .../docs/content/guides/auth/quickstarts/react.mdx | 2 -- .../content/guides/getting-started/api-keys.mdx | 10 +--------- .../getting-started/migrating-to-new-api-keys.mdx | 8 +------- apps/docs/content/guides/realtime/broadcast.mdx | 13 ++----------- apps/docs/content/guides/realtime/presence.mdx | 13 ++----------- 10 files changed, 24 insertions(+), 75 deletions(-) create mode 100644 apps/docs/content/_partials/api_keys_deprecation.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index c77840d6ce9..d2fdb96c6be 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -338,7 +338,7 @@ export const gettingstarted: NavMenuConstant = { items: [ { name: 'Build with AI tools', url: '/guides/ai-tools' }, { name: 'API Keys', url: '/guides/getting-started/api-keys' }, - { name: 'Local Development', url: '/guides/cli/getting-started' }, + { name: 'Local Development', url: '/guides/local-development/cli/getting-started' }, { name: 'Architecture', url: '/guides/getting-started/architecture' }, { name: 'Migrating to new API keys', diff --git a/apps/docs/content/_partials/api_keys_deprecation.mdx b/apps/docs/content/_partials/api_keys_deprecation.mdx new file mode 100644 index 00000000000..74a2dd173bb --- /dev/null +++ b/apps/docs/content/_partials/api_keys_deprecation.mdx @@ -0,0 +1,12 @@ + + +Supabase has changed the way keys work to improve project security and developer experience. You can [read the full announcement on GitHub](https://github.com/orgs/supabase/discussions/29260). + +**They will be deprecated by the end of 2026, and you should now use the publishable (`sb_publishable_xxx`) and secret (`sb_secret_xxx`) keys instead**. + +In most cases, you can get keys from [the Project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}), but if you want a specific key, you can find them in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. + +- **For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section for client-side operations. For server-side operations, copy the value from the **Secret keys** section. +- **For legacy keys**, copy the `anon` key for client-side operations and the `service_role` key for server-side operations from the **Legacy API Keys** tab. + + diff --git a/apps/docs/content/_partials/api_settings.mdx b/apps/docs/content/_partials/api_settings.mdx index 1ff65a3332f..b60a575b2e5 100644 --- a/apps/docs/content/_partials/api_settings.mdx +++ b/apps/docs/content/_partials/api_settings.mdx @@ -6,15 +6,5 @@ To do this, you need to get the Project URL and key from [the project **Connect* [Read the API keys docs](/docs/guides/getting-started/api-keys) for a full explanation of all key types and their uses. - - -Supabase is changing the way keys work to improve project security and developer experience. You can [read the full announcement on GitHub](https://github.com/orgs/supabase/discussions/29260). - -The older `anon` and `service_role` keys will work until the end of 2026 but **we strongly encourage switching to and using** the new publishable (`sb_publishable_xxx`) and secret (`sb_secret_xxx`) keys now. - -In most cases, you can get keys from [the Project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}), but if you want a specific key, you can find them in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. - -- **For legacy keys**, copy the `anon` key for client-side operations and the `service_role` key for server-side operations from the **Legacy API Keys** tab. -- **For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section. - - +<$Partial path="api_keys_deprecation.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }} +/> diff --git a/apps/docs/content/_partials/api_settings_steps.mdx b/apps/docs/content/_partials/api_settings_steps.mdx index 50d45feb465..19b199f746b 100644 --- a/apps/docs/content/_partials/api_settings_steps.mdx +++ b/apps/docs/content/_partials/api_settings_steps.mdx @@ -8,15 +8,5 @@ To do this, you need to get the Project URL and key from [the project **Connect* [Read the API keys docs](/docs/guides/getting-started/api-keys) for a full explanation of all key types and their uses. - - -Supabase is changing the way keys work to improve project security and developer experience. You can [read the full announcement on GitHub](https://github.com/orgs/supabase/discussions/29260). - -The older `anon` and `service_role` keys will work until the end of 2026 but **we strongly encourage switching to and using** the new publishable (`sb_publishable_xxx`) and secret (`sb_secret_xxx`) keys now. - -In most cases, you can get keys from [the Project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}), but if you want a specific key, you can find them in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. - -- **For legacy keys**, copy the `anon` key for client-side operations and the `service_role` key for server-side operations from the **Legacy API Keys** tab. -- **For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section. - - +<$Partial path="api_keys_deprecation.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }} +/> diff --git a/apps/docs/content/guides/api/creating-routes.mdx b/apps/docs/content/guides/api/creating-routes.mdx index 7b065aabe7a..701bf327560 100644 --- a/apps/docs/content/guides/api/creating-routes.mdx +++ b/apps/docs/content/guides/api/creating-routes.mdx @@ -66,16 +66,7 @@ Every Supabase project has a unique API URL. Your API is secured behind an API g To do this, you need to get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/_?showConnect=true). - - -Supabase is changing the way keys work to improve project security and developer experience. You can [read the full announcement](https://github.com/orgs/supabase/discussions/29260), but in the transition period, you can use both the current `anon` and `service_role` keys and the new publishable key with the form `sb_publishable_xxx` which will replace the older keys. - -In most cases, you can get the correct key from [the Project's **Connect** dialog](/dashboard/project/_?showConnect=true), but if you want a specific key, you can find all keys in [the API Keys section of a Project's Settings page](/dashboard/project/_/settings/api-keys/): - -- **For legacy keys**, copy the `anon` key for client-side operations and the `service_role` key for server-side operations from the **Legacy API Keys** tab. -- **For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section. - - +<$Partial path="api_keys_deprecation.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }} /> [Read the API keys docs](/docs/guides/getting-started/api-keys) for a full explanation of all key types and their uses. diff --git a/apps/docs/content/guides/auth/quickstarts/react.mdx b/apps/docs/content/guides/auth/quickstarts/react.mdx index 6d498228376..7c99938fecd 100644 --- a/apps/docs/content/guides/auth/quickstarts/react.mdx +++ b/apps/docs/content/guides/auth/quickstarts/react.mdx @@ -68,8 +68,6 @@ hideToc: true - - diff --git a/apps/docs/content/guides/getting-started/api-keys.mdx b/apps/docs/content/guides/getting-started/api-keys.mdx index 44f97cb20a2..696c9578bbe 100644 --- a/apps/docs/content/guides/getting-started/api-keys.mdx +++ b/apps/docs/content/guides/getting-started/api-keys.mdx @@ -32,15 +32,7 @@ There are 4 types of API keys that you can use with Supabase: | `anon` | JWT (long lived) | Low | Platform, CLI | Legacy version of publishable keys. | | `service_role` | JWT (long lived) | Elevated | Platform, CLI | Legacy version of secret keys. | - - -Supabase has changed the way keys work to improve project security and developer experience. You can read [the full announcement](https://github.com/orgs/supabase/discussions/29260). - -`anon` and `service_role` keys are based on the project's JWT secret. They are generated when your project is created and you can only change them when you rotate the JWT secret. This can cause significant issues in production applications. **You should now use the `sb_publishable_xxx` and `sb_secret_xxx` keys instead**. See [Migrate to publishable and secret API keys](/docs/guides/getting-started/migrating-to-new-api-keys) for a step-by-step guide. - -You can still find legacy keys in the **Legacy anon, service_role API keys** tab of the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard: - - +<$Partial path="api_keys_deprecation.mdx" /> ## Publishable keys diff --git a/apps/docs/content/guides/getting-started/migrating-to-new-api-keys.mdx b/apps/docs/content/guides/getting-started/migrating-to-new-api-keys.mdx index 0a7d3f29d46..8ad184491b2 100644 --- a/apps/docs/content/guides/getting-started/migrating-to-new-api-keys.mdx +++ b/apps/docs/content/guides/getting-started/migrating-to-new-api-keys.mdx @@ -4,16 +4,10 @@ title: 'Migrating to publishable and secret API keys' description: 'Move from legacy JWT-based anon and service_role keys to publishable and secret keys.' --- -Supabase has changed the way API keys work. The legacy `anon` and `service_role` keys are based on your project's JWT secret, which makes them hard to rotate without downtime. The new publishable (`sb_publishable_...`) and secret (`sb_secret_...`) keys can be created, named, and revoked independently, so you can rotate a single key without touching the rest of your app. +<$Partial path="api_keys_deprecation.mdx" /> This guide covers migrating an **existing project.** Both key types work simultaneously, so you can swap clients one at a time and deactivate the legacy keys only after nothing depends on them. - - -The legacy `anon` and `service_role` keys keep working until the end of 2026. You don't have to migrate today, but doing it early lets you rotate keys safely from now on. - - - ## Before you start The migration maps onto your existing keys: diff --git a/apps/docs/content/guides/realtime/broadcast.mdx b/apps/docs/content/guides/realtime/broadcast.mdx index 5bbb3fe15c1..a6f73498569 100644 --- a/apps/docs/content/guides/realtime/broadcast.mdx +++ b/apps/docs/content/guides/realtime/broadcast.mdx @@ -37,17 +37,8 @@ You can use the Supabase client libraries to receive Broadcast messages. Get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/_?showConnect=true). - - -Supabase is changing the way keys work to improve project security and developer experience. You can [read the full announcement](https://github.com/orgs/supabase/discussions/29260), but in the transition period, you can use both the current `anon` and `service_role` keys and the new publishable key with the form `sb_publishable_xxx` which will replace the older keys. - -**The legacy keys will be deprecated shortly, so we strongly encourage switching to and using the new publishable and secret API keys**. - -In most cases, you can get the correct key from [the Project's **Connect** dialog](/dashboard/project/_?showConnect=true), but if you want a specific key, you can find all keys in [the API Keys section of a Project's Settings page](/dashboard/project/_/settings/api-keys/): - -**For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section. - - +<$Partial path="api_keys_deprecation.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }} +/> - -Supabase is changing the way keys work to improve project security and developer experience. You can [read the full announcement](https://github.com/orgs/supabase/discussions/29260), but in the transition period, you can use both the current `anon` and `service_role` keys and the new publishable key with the form `sb_publishable_xxx` which will replace the older keys. - -**The legacy keys will be deprecated shortly, so we strongly encourage switching to and using the new publishable and secret API keys**. - -In most cases, you can get the correct key from [the Project's **Connect** dialog](/dashboard/project/_?showConnect=true), but if you want a specific key, you can find all keys in [the API Keys section of a Project's Settings page](/dashboard/project/_/settings/api-keys/): - -**For new keys**, open the **API Keys** tab, if you don't have a publishable key already, click **Create new API Keys**, and copy the value from the **Publishable key** section. - - +<$Partial path="api_keys_deprecation.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }} +/>