docs: update api keys guide

apps/docs/components/MDX/database_setup.mdx

@@ -15,4 +15,4 @@ Your database will be available in less than a minute.
 You can find your project credentials inside the project [settings](https://supabase.com/dashboard/project/_/settings/), including:
 
 - [Database credentials](https://supabase.com/dashboard/project/_/settings/database): connection strings and connection pooler details.
-- [API credentials](https://supabase.com/dashboard/project/_/settings/database): your serverless API URL and `anon` / `service_role` keys.
+- [API credentials](https://supabase.com/dashboard/project/_/settings/database): your serverless API URL and <PublishableKey/> / `service_role` keys.

apps/docs/components/MDX/kotlin_project_setup.mdx

@@ -40,10 +40,10 @@ Now we are going to set up the database schema. You can just copy/paste the SQL
 ### Get the API Keys
 
 Now that you've created some database tables, you are ready to insert data using the auto-generated API.
-We just need to get the Project URL and `anon` key from the API settings.
+We just need to get the Project URL and <PublishableKey/> key from the API settings.
 
 1. Go to the [API Settings](https://app.supabase.com/project/_/settings/api) page in the Dashboard.
-2. Find your Project `URL`, `anon`, and `service_role` keys on this page.
+2. Find your Project `URL`, <PublishableKey/>, and `service_role` keys on this page.
 
 ### Set up Google Authentication
 

apps/docs/components/MDX/partials.tsx

@@ -10,6 +10,7 @@ import KotlinProjectSetup from './kotlin_project_setup.mdx'
 import MigrationWarnings from './migration_warnings.mdx'
 import OAuthPkceFlow from './oauth_pkce_flow.mdx'
 import ProjectSetup from './project_setup.mdx'
+import PublishableKey from './publishable_key.mdx'
 import QuickstartDbSetup from './quickstart_db_setup.mdx'
 import QuickstartIntro from './quickstart_intro.mdx'
 import SocialProviderSettingsSupabase from './social_provider_settings_supabase.mdx'
@@ -25,6 +26,7 @@ export {
   KotlinProjectSetup,
   MigrationWarnings,
   ProjectSetup,
+  PublishableKey,
   OAuthPkceFlow,
   QuickstartDbSetup,
   QuickstartIntro,

apps/docs/components/MDX/project_setup.mdx

@@ -62,7 +62,7 @@ supabase migration new user_management_starter
 ### Get the API Keys
 
 Now that you've created some database tables, you are ready to insert data using the auto-generated API.
-We just need to get the Project URL and `anon` key from the API settings.
+We just need to get the Project URL and <PublishableKey/> key from the API settings.
 
 1. Go to the [API Settings](https://supabase.com/dashboard/project/_/settings/api) page in the Dashboard.
-1. Find your Project `URL`, `anon`, and `service_role` keys on this page.
+1. Find your Project `URL`, <PublishableKey/>, and `service_role` keys on this page.

apps/docs/components/MDX/publishable_key.mdx

@@ -0,0 +1,10 @@
+import { TooltipProvider_Shadcn_, Tooltip_Shadcn_, TooltipTrigger_Shadcn_, TooltipContent_Shadcn_ } from 'ui'
+
+<TooltipProvider_Shadcn_>
+  <Tooltip_Shadcn_>
+    <TooltipTrigger_Shadcn_>`publishable`</TooltipTrigger_Shadcn_>
+    <TooltipContent_Shadcn_ className="text-sm">
+      <p>equivalent to the `anon` key</p>
+    </TooltipContent_Shadcn_>
+  </Tooltip_Shadcn_>
+</TooltipProvider_Shadcn_>

apps/docs/content/guides/api/api-keys.mdx

@@ -4,23 +4,20 @@ title: 'Understanding API Keys'
 description: 'Securing your Data API with Postgres Row Level Security.'
 ---
 
-Supabase provides two default keys when you create a project: an `anon` key, and a `service_role` key. You can find both keys in the [API Settings](https://supabase.com/dashboard/project/_/settings/api).
+Supabase provides 2 default keys when you create a project: a <PublishableKey/> key, and a `secret` key. You can find both keys in the [API Settings](https://supabase.com/dashboard/project/_/settings/api).
 
-The data APIs are designed to work with Postgres Row Level Security (RLS). These keys both map to Postgres roles. You can find an `anon` user and a `service_role` user in the [Roles](http://supabase.com/dashboard/project/_/database/roles) section of the dashboard.
+The data APIs are designed to work with Postgres Row Level Security (RLS). These keys map to the following Postgres roles:
 
-The keys are both long-lived JWTs. If you decode these keys, you will see that they contain the "role", an "issued date", and an "expiry date" ~10 years in the future.
+| Key           | Postgres Role  |
+| ------------- | -------------- |
+| `publishable` | `anon`         |
+| `secret`      | `service_role` |
 
-```json
-{
-  "role": "anon",
-  "iat": 1625137684,
-  "exp": 1940713684
-}
-```
+You can find an `anon` user and a `service_role` user in the [Roles](http://supabase.com/dashboard/project/_/database/roles) section of the dashboard.
 
-## The `anon` key
+## Publishable key
 
-The `anon` key has very few privileges. You can use it in your [RLS policies](/docs/guides/database/postgres/row-level-security) to allow unauthenticated access. For example, this policy will allow unauthenticated access to the `profiles` table:
+The `publishable` key maps to the `anon` Postgres role, which has very few privileges. You can use it in your [RLS policies](/docs/guides/database/postgres/row-level-security) to allow unauthenticated access. For example, this policy will allow unauthenticated access to the `profiles` table:
 
 ```sql
 create policy "Allow public access" on profiles to anon for
@@ -44,23 +41,45 @@ select
   using (true);
 ```
 
-## The `service_role` key
+## Secret key
 
-The "service_role" is a predefined Postgres role with elevated privileges, designed to perform various administrative and service-related tasks. It can bypass Row Level Security, so it should only be used on a private server.
+The `secret` key maps to the `service_role` Postgres role, which is a predefined Postgres role with elevated privileges, designed to perform various administrative and service-related tasks. It can bypass Row Level Security, so it should only be used on a private server.
 
 <Admonition type="caution">
 
-Never expose the `service_role` key in a browser or anywhere where a user can see it.
+Never expose the `secret` key in a browser or anywhere where a user can see it.
 
 </Admonition>
 
-A common use case for the `service_role` key is running data analytics jobs on the backend. To support joins on user id, it is often useful to grant the service role read access to `auth.users` table.
+A common use case for the `secret` key is running data analytics jobs on the backend. To support joins on user id, it is often useful to grant the service role read access to `auth.users` table.
 
 ```sql
 grant
 select
   on table auth.users to service_role;
 ```
 
+## Legacy API Keys
+
+<Admonition type="warning" label="Legacy API keys">
+
+The `anon` and `service_role` keys are being deprecated on 1st May 2025 for new and restored projects. For existing projects, these keys will be deprecated on 1st October 2025. For more information, read the [announcement](https://github.com/orgs/supabase/discussions/29260).
+
+</Admonition>
+
+You can find the `anon` and `service_role` keys in the [API Settings](https://supabase.com/dashboard/project/_/settings/api).
+
+The data APIs are designed to work with Postgres Row Level Security (RLS). These keys both map to Postgres roles. You can find an `anon` user and a `service_role` user in the [Roles](http://supabase.com/dashboard/project/_/database/roles) section of the dashboard.
+
+The keys are both long-lived JWTs. If you decode these keys, you will see that they contain the "role", an "issued date", and an "expiry date" ~10 years in the future.
+
+```json
+{
+  "role": "anon",
+  "iat": 1625137684,
+  "exp": 1940713684
+}
+```
+
 We have [partnered with GitHub](https://github.blog/changelog/2022-03-28-supabase-is-now-a-github-secret-scanning-partner/) to scan for Supabase `service_role` keys pushed to public repositories.
 If they detect any keys with service_role privileges being pushed to GitHub, they will forward the API key to us, so that we can automatically revoke the detected secrets and notify you, protecting your data against malicious actors.

apps/docs/content/guides/api/creating-routes.mdx

@@ -54,7 +54,7 @@ Every Supabase project has a unique API URL. Your API is secured behind an API g
 
 1. Go to the [Settings](https://supabase.com/dashboard/project/_/settings/general) page in the Dashboard.
 2. Click **API** in the sidebar.
-3. Find your API `URL`, `anon`, and `service_role` keys on this page.
+3. Find your API `URL`, <PublishableKey/>, and `service_role` keys on this page.
 
 <video width="99%" muted playsInline controls={true}>
   <source
@@ -65,7 +65,7 @@ Every Supabase project has a unique API URL. Your API is secured behind an API g
 
 The REST API is accessible through the URL `https://<project_ref>.supabase.co/rest/v1`
 
-Both of these routes require the `anon` key to be passed through an `apikey` header.
+Both of these routes require the <PublishableKey/> key to be passed through an `apikey` header.
 
 ## Using the API
 

apps/docs/content/guides/auth/auth-anonymous.mdx

@@ -12,7 +12,7 @@ Calling `signInAnonymously()` creates an anonymous user. It's just like a perman
 
 Like permanent users, the `authenticated` Postgres role will be used when using the Data APIs to access your project. JWTs for these users will have an `is_anonymous` claim which you can use to distinguish in RLS policies.
 
-This is different from the `anon` API key which does not create a user and can be used to implement public access to your database as it uses the `anonymous` Postgres role.
+This is different from the <PublishableKey/> API key which does not create a user and can be used to implement public access to your database as it uses the `anon` Postgres role.
 
 </Admonition>
 

apps/docs/content/guides/getting-started/tutorials/with-angular.mdx

@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in the `src/environments/environment.ts` file.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.
 
 ```ts src/environments/environment.ts

apps/docs/content/guides/getting-started/tutorials/with-expo-react-native.mdx

@@ -38,7 +38,7 @@ npx expo install @supabase/supabase-js @react-native-async-storage/async-storage
 ```
 
 Now let's create a helper file to initialize the Supabase client.
-We need the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+We need the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 These variables are safe to expose in your Expo app since Supabase has
 [Row Level Security](/docs/guides/auth#row-level-security) enabled on your Database.
 

apps/docs/content/guides/getting-started/tutorials/with-ionic-angular.mdx

@@ -37,7 +37,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally, we want to save the environment variables in the `src/environments/environment.ts` file.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.
 
 ```ts environment.ts

apps/docs/content/guides/getting-started/tutorials/with-ionic-react.mdx

@@ -37,7 +37,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 REACT_APP_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-ionic-vue.mdx

@@ -37,7 +37,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 VUE_APP_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx

@@ -55,7 +55,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env.local`.
-Create a `.env.local` file at the root of the project, and paste the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+Create a `.env.local` file at the root of the project, and paste the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env.local
 NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-nuxt-3.mdx

@@ -36,7 +36,7 @@ npm install @nuxtjs/supabase --save-dev
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 SUPABASE_URL="YOUR_SUPABASE_URL"

apps/docs/content/guides/getting-started/tutorials/with-react.mdx

@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env.local` file.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-redwoodjs.mdx

@@ -103,7 +103,7 @@ Say, **yes** and it will setup the Supabase client in your app and also provide
 ```
 
 Next, we want to save the environment variables in a `.env`.
-We need the `API URL` as well as the `anon` and `jwt_secret` keys that you copied [earlier](#get-the-api-keys).
+We need the `API URL` as well as the <PublishableKey/> and `jwt_secret` keys that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-refine.mdx

@@ -83,7 +83,7 @@ export const supabaseClient = createClient(supabaseUrl, supabaseAnonKey, {
 })
 ```
 
-And then, we want to save the environment variables in a `.env.local` file. All you need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+And then, we want to save the environment variables in a `.env.local` file. All you need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env.local
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-solidjs.mdx

@@ -35,7 +35,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-svelte.mdx

@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/getting-started/tutorials/with-swift.mdx

@@ -28,7 +28,7 @@ Add the [supabase-swift](https://github.com/supabase/supabase-swift) dependency.
 Add the `https://github.com/supabase/supabase-swift` package to your app. For instructions, see the [Apple tutorial on adding package dependencies](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
 
 Create a helper file to initialize the Supabase client.
-You need the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+You need the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 These variables will be exposed on the application, and that's completely fine since you have
 [Row Level Security](/docs/guides/auth#row-level-security) enabled on your database.
 

apps/docs/content/guides/getting-started/tutorials/with-vue-3.mdx

@@ -41,7 +41,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally we want to save the environment variables in a `.env`.
-All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All we need are the API URL and the <PublishableKey/> key that you copied [earlier](#get-the-api-keys).
 
 ```bash .env
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL

apps/docs/content/guides/realtime/broadcast.mdx

@@ -12,7 +12,7 @@ You can use the Supabase client libraries to send and receive Broadcast messages
 
 ### Initialize the client
 
-Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.
+Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and <PublishableKey/> key.
 
 <Tabs
   scrollable

apps/docs/content/guides/realtime/presence.mdx

@@ -12,7 +12,7 @@ You can use the Supabase client libraries to track Presence state between users.
 
 ### Initialize the client
 
-Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.
+Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and <PublishableKey/> key.
 
 <Tabs
   scrollable

apps/docs/features/docs/MdxBase.shared.tsx

@@ -22,6 +22,7 @@ import {
   HuggingFaceDeployment,
   KotlinProjectSetup,
   MigrationWarnings,
+  PublishableKey,
   OAuthPkceFlow,
   ProjectSetup,
   QuickstartDbSetup,
@@ -73,6 +74,7 @@ const components = {
   OAuthPkceFlow,
   ProjectConfigVariables,
   ProjectSetup,
+  PublishableKey,
   QuickstartDbSetup,
   QuickstartIntro,
   RealtimeLimitsEstimator,