docs: Clear up keys and connection instructions in web getting started guides [DO NOT MERGE] (supabase#38554)

ChrisChinchilla · github-actions[bot] · web-flow · commit d91ea9d4e24c · 2025-09-12T11:35:34.000Z
* Clearup keys and connection instructions in web getting started guides

* Update apps/docs/content/_partials/project_setup.mdx

Co-authored-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;

* Update apps/docs/content/_partials/project_setup.mdx

Co-authored-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;

* prettier

* second try

* Fix keys for getting started section

* Updated keys for auth section, SSR aside

* Remove mention of dropdowns for now

---------

Co-authored-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;
diff --git a/apps/docs/content/_partials/api_settings.mdx b/apps/docs/content/_partials/api_settings.mdx
@@ -0,0 +1,16 @@
+### Get API details
+
+Now that you've created some database tables, you are ready to insert data using the auto-generated API.
+
+To do this, you need to get the Project URL and key. Get the URL from [the API settings section](/dashboard/project/_/settings/api) of a project and the key from the [the API Keys section of a project's Settings page](/dashboard/project/_/settings/api-keys/).
+
+<Admonition type="note" title="Changes to API keys">
+
+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.
+
+To get the key values, open [the API Keys section of a project's Settings page](/dashboard/project/_/settings/api-keys/) and do the following:
+
+- **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.
+
+</Admonition>
diff --git a/apps/docs/content/_partials/api_settings_steps.mdx b/apps/docs/content/_partials/api_settings_steps.mdx
@@ -0,0 +1,12 @@
+{/* TODO: How to completely consolidate partials? */}
+
+<Admonition type="note" title="Changes to API keys">
+
+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.
+
+To get the key values, open [the API Keys section of a project's Settings page](/dashboard/project/_/settings/api-keys/) and do the following:
+
+- **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.
+
+</Admonition>
diff --git a/apps/docs/content/_partials/kotlin_project_setup.mdx b/apps/docs/content/_partials/kotlin_project_setup.mdx
@@ -33,13 +33,7 @@ Now we are going to set up the database schema. You can just copy/paste the SQL
 </TabPanel>
 </Tabs>
 
-### 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.
-
-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.
+<$Partial path="api_settings.mdx" />
 
 ### Set up Google authentication
 
diff --git a/apps/docs/content/_partials/project_setup.mdx b/apps/docs/content/_partials/project_setup.mdx
@@ -55,11 +55,4 @@ supabase migration new user_management_starter
 </TabPanel>
 </Tabs>
 
-### Get the API keys
-
-Now that you've created some database tables, you are ready to insert data using the auto-generated API.
-
-To do this, you need to get the Project URL and `anon` key from the API settings.
-
-1. Go to the [API Settings](/dashboard/project/_/settings/api) page in the Dashboard.
-2. Find your Project `URL`, `anon`, and `service_role` keys on this page.
+<$Partial path="api_settings.mdx" />
diff --git a/apps/docs/content/guides/auth/quickstarts/nextjs.mdx b/apps/docs/content/guides/auth/quickstarts/nextjs.mdx
@@ -52,15 +52,17 @@ hideToc: true
   <StepHikeCompact.Step step={3}>
     <StepHikeCompact.Details title="Declare Supabase Environment Variables">
 
-    Rename `.env.example` to `.env.local` and populate with [your project's URL and Anon Key](/dashboard/project/_/settings/api).
+    Rename `.env.example` to `.env.local` and populate with [your project's URL and Key](/dashboard/project/_/settings/api).
+
+    <$Partial path="api_settings_steps.mdx" />
 
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
 
       ```text name=.env.local
-        NEXT_PUBLIC_SUPABASE_URL=your-project-url
-        NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... or anon key
+      NEXT_PUBLIC_SUPABASE_URL=your-project-url
+      NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... or anon key
       ```
 
     </StepHikeCompact.Code>
diff --git a/apps/docs/content/guides/auth/quickstarts/react-native.mdx b/apps/docs/content/guides/auth/quickstarts/react-native.mdx
@@ -64,7 +64,9 @@ hideToc: true
   <StepHikeCompact.Step step={4}>
     <StepHikeCompact.Details title="Set up your login component">
 
-    Create a helper file `lib/supabase.ts` that exports a Supabase client using your [Project URL and public API (anon) key](/dashboard/project/_/settings/api).
+    Create a helper file `lib/supabase.ts` that exports a Supabase client using your Project URL and key.
+
+    <$Partial path="api_settings_steps.mdx" />
 
     </StepHikeCompact.Details>
     <StepHikeCompact.Code>
diff --git a/apps/docs/content/guides/auth/quickstarts/react.mdx b/apps/docs/content/guides/auth/quickstarts/react.mdx
@@ -64,7 +64,9 @@ hideToc: true
   <StepHikeCompact.Step step={4}>
     <StepHikeCompact.Details title="Set up your login component">
 
-    In `App.jsx`, create a Supabase client using your [Project URL and public API (anon) key](/dashboard/project/_/settings/api).
+    In `App.jsx`, create a Supabase client using your Project URL and key.
+
+    <$Partial path="api_settings_steps.mdx" />
 
     You can configure the Auth component to display whenever there is no session inside `supabase.auth.getSession()`
 
diff --git a/apps/docs/content/guides/getting-started/quickstarts/nuxtjs.mdx b/apps/docs/content/guides/getting-started/quickstarts/nuxtjs.mdx
@@ -74,7 +74,7 @@ hideToc: true
           runtimeConfig: {
             public: {
               supabaseUrl: process.env.SUPABASE_URL,
-              supabaseAnonKey: process.env.SUPABASE_PUBLISHABLE_KEY,
+              supabasePublishableKey: process.env.SUPABASE_PUBLISHABLE_KEY,
             },
           },
         });
@@ -99,7 +99,7 @@ hideToc: true
       <script setup>
       import { createClient } from '@supabase/supabase-js'
       const config = useRuntimeConfig()
-      const supabase = createClient(config.public.supabaseUrl, config.public.supabaseAnonKey)
+      const supabase = createClient(config.public.supabaseUrl, config.public.supabasePublishableKey)
       const instruments = ref([])
 
       async function getInstruments() {
diff --git a/apps/docs/content/guides/getting-started/quickstarts/vue.mdx b/apps/docs/content/guides/getting-started/quickstarts/vue.mdx
@@ -88,9 +88,9 @@ hideToc: true
       import { createClient } from '@supabase/supabase-js'
 
       const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-      const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+      const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
-      export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+      export const supabase = createClient(supabaseUrl, supabasePublishableKey)
       ```
 
     </StepHikeCompact.Code>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-angular.mdx b/apps/docs/content/guides/getting-started/tutorials/with-angular.mdx
@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 Finally, save the environment variables in the `src/environments/environment.ts` file.
-All you need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All you need are the API URL and the key that you copied [earlier](#get-api-details).
 The application exposes these variables in the browser, and that's fine as you have [Row Level Security](/docs/guides/auth#row-level-security) enabled on the Database.
 
 <$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-expo-react-native.mdx b/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 key that you copied [earlier](#get-api-details).
 These variables are safe to expose in your Expo app since Supabase has
 [Row Level Security](/docs/guides/database/postgres/row-level-security) enabled on your Database.
 
@@ -58,9 +58,9 @@ These variables are safe to expose in your Expo app since Supabase has
     import { createClient } from '@supabase/supabase-js'
 
     const supabaseUrl = YOUR_REACT_NATIVE_SUPABASE_URL
-    const supabaseAnonKey = YOUR_REACT_NATIVE_SUPABASE_PUBLISHABLE_KEY
+    const supabasePublishableKey = YOUR_REACT_NATIVE_SUPABASE_PUBLISHABLE_KEY
 
-    export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    export const supabase = createClient(supabaseUrl, supabasePublishableKey, {
       auth: {
         storage: AsyncStorage,
         autoRefreshToken: true,
@@ -150,9 +150,9 @@ These variables are safe to expose in your Expo app since Supabase has
     }
 
     const supabaseUrl = YOUR_REACT_NATIVE_SUPABASE_URL
-    const supabaseAnonKey = YOUR_REACT_NATIVE_SUPABASE_PUBLISHABLE_KEY
+    const supabasePublishableKey = YOUR_REACT_NATIVE_SUPABASE_PUBLISHABLE_KEY
 
-    const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+    const supabase = createClient(supabaseUrl, supabasePublishableKey, {
       auth: {
         storage: new LargeSecureStore(),
         autoRefreshToken: true,
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-ionic-angular.mdx b/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 key that you copied [earlier](#get-api-details).
 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.
 
 <$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-ionic-react.mdx b/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 key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
@@ -57,9 +57,9 @@ on the browser, and that's completely fine since we have [Row Level Security](/d
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || ''
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY || ''
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY || ''
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createClient(supabaseUrl, supabasePublishableKey)
 ```
 
 </$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-ionic-vue.mdx b/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 key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
@@ -56,9 +56,9 @@ Now that we have the API credentials in place, let's create a helper file to ini
 import { createClient } from '@supabase/supabase-js';
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL as string;
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY as string;
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY as string;
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+export const supabase = createClient(supabaseUrl, supabasePublishableKey);
 ```
 
 </$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx b/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx
@@ -54,7 +54,7 @@ Then install the Supabase client library: [supabase-js](https://github.com/supab
 npm install @supabase/supabase-js
 ```
 
-Save the environment variables in 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).
+Save the environment variables in a `.env.local` file at the root of the project, and paste the API URL and the key that you copied [earlier](#get-api-details).
 
 ```bash .env.local
 NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-nuxt-3.mdx b/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 key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-react.mdx b/apps/docs/content/guides/getting-started/tutorials/with-react.mdx
@@ -13,7 +13,7 @@ If you get stuck while working through this guide, refer to the [full example on
 
 </Admonition>
 
-<$Partial path="project_setup.mdx" />
+<$Partial path="project_setup.mdx" variables={{ "framework": "React" }} />
 
 ## Building the app
 
@@ -35,8 +35,8 @@ Then let's install the only additional dependency: [supabase-js](https://github.
 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).
+And finally, save the environment variables in a `.env.local` file.
+All we need are the Project URL and the key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
@@ -58,9 +58,9 @@ Create and edit `src/supabaseClient.js`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createClient(supabaseUrl, supabasePublishableKey)
 ```
 
 </$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-redwoodjs.mdx b/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 key and `jwt_secret` that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-refine.mdx b/apps/docs/content/guides/getting-started/tutorials/with-refine.mdx
@@ -63,7 +63,7 @@ Let's move ahead to understand the generated code now.
 
 ### Refine `supabaseClient`
 
-The `create refine-app` generated a Supabase client for us in the `src/utility/supabaseClient.ts` file. It has two constants: `SUPABASE_URL` and `SUPABASE_KEY`. We want to replace them as `supabaseUrl` and `supabaseAnonKey` respectively and assign them our own Supabase server's values.
+The `create refine-app` generated a Supabase client for us in the `src/utility/supabaseClient.ts` file. It has two constants: `SUPABASE_URL` and `SUPABASE_KEY`. We want to replace them as `supabaseUrl` and `supabasePublishableKey` respectively and assign them our own Supabase server's values.
 
 We'll update it with environment variables managed by Vite:
 
@@ -73,9 +73,9 @@ We'll update it with environment variables managed by Vite:
 import { createClient } from '@refinedev/supabase'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
-export const supabaseClient = createClient(supabaseUrl, supabaseAnonKey, {
+export const supabaseClient = createClient(supabaseUrl, supabasePublishableKey, {
   db: {
     schema: 'public',
   },
@@ -87,7 +87,7 @@ export const supabaseClient = createClient(supabaseUrl, supabaseAnonKey, {
 
 </$CodeTabs>
 
-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 key that you copied [earlier](#get-api-details).
 
 ```bash .env.local
 VITE_SUPABASE_URL=YOUR_SUPABASE_URL
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-solidjs.mdx b/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 key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
@@ -55,9 +55,9 @@ on the browser, and that's completely fine since we have [Row Level Security](/d
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createClient(supabaseUrl, supabasePublishableKey)
 ```
 
 </$CodeTabs>
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-svelte.mdx b/apps/docs/content/guides/getting-started/tutorials/with-svelte.mdx
@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 Finally, save the environment variables in a `.env`.
-All you need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
+All you need are the API URL and the key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-sveltekit.mdx b/apps/docs/content/guides/getting-started/tutorials/with-sveltekit.mdx
@@ -36,7 +36,7 @@ npm install @supabase/supabase-js
 ```
 
 And finally, save the environment variables in a `.env` file.
-All you need are the `PUBLIC_SUPABASE_URL` and the `PUBLIC_SUPABASE_ANON_KEY` key that you copied [earlier](#get-the-api-keys).
+All you need are the `PUBLIC_SUPABASE_URL` and the key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-swift.mdx b/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 key that you copied [earlier](#get-api-details).
 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.
 
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-vue-3.mdx b/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 key that you copied [earlier](#get-api-details).
 
 <$CodeTabs>
 
@@ -61,9 +61,9 @@ on the browser, and that's completely fine since we have [Row Level Security](/d
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createClient(supabaseUrl, supabasePublishableKey)
 ```
 
 </$CodeTabs>
