docs: Check and clarify API keys (#41200)

* Update parial * Add partial to quickstarts * Auth section * More * Prettier * Realtime * Add soft links to frameworks * Add tab * Fix typo * More changes * Updates * Prettier
2026-05-06 08:56:46 -04:00 · 2025-12-15 16:45:21 +01:00
parent 52e62a69f1
commit a3b7c8f3a7
42 changed files with 132 additions and 45 deletions
@@ -2,15 +2,17 @@

 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/).
+To do this, you need to get the Project URL and key from [the project **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}).

 <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:
+In most cases, you can get the correct key from [the Project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}), 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.

 </Admonition>
+
+[Read the API keys docs](/docs/guides/api/api-keys) for a full explanation of all key types and their uses.
@@ -1,12 +1,16 @@
 {/* TODO: How to completely consolidate partials? */}

+You can also get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}).
+
 <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:
+In most cases, you can get the correct key from [the Project's **Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}), 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.

 </Admonition>
+
+[Read the API keys docs](/docs/guides/api/api-keys) for a full explanation of all key types and their uses.
@@ -33,7 +33,8 @@ Now we are going to set up the database schema. You can just copy/paste the SQL
 </TabPanel>
 </Tabs>

-<$Partial path="api_settings.mdx" />
+<$Partial path="api_settings.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }}
+/>

 ### Set up Google authentication

@@ -23,7 +23,7 @@ className="rounded-lg border border-foreground/10 bg-surface-100 text-foreground
    3. Authenticate with HTTP Basic Auth:

    - **Username**: `service_role`
-    - **Password**: a service role secret (JWT) from [**Project Settings > JWT** (opens in a new tab)](/dashboard/project/_/settings/jwt) or any other Secret API key from [**Project Settings > API keys** (opens in a new tab)](/dashboard/project/_/settings/api-keys)
+    - **Password**: a service role secret (JWT) from [**Project Settings > JWT**](/dashboard/project/_/settings/jwt) or any other Secret API key from [**Project Settings > API keys** (opens in a new tab)](/dashboard/project/_/settings/api-keys)

    Testing locally is as simple as running `curl` with your service role secret:

@@ -34,7 +34,7 @@ className="rounded-lg border border-foreground/10 bg-surface-100 text-foreground

    You can provision long-lived automation tokens in two ways:

-    - Create an account access token once at [**Account Settings > Access Tokens (opens in a new tab)**](/dashboard/account/tokens) and reuse it wherever you configure observability tooling.
+    - Create an account access token once at [**Account Settings > Access Tokens**](/dashboard/account/tokens) and reuse it wherever you configure observability tooling.
    - **Optional**: programmatically exchange an access token for project API keys via the [Management API ](/docs/reference/api/management-projects-api-keys-retrieve').

    ```bash
@@ -55,4 +55,5 @@ supabase migration new user_management_starter
 </TabPanel>
 </Tabs>

-<$Partial path="api_settings.mdx" />
+<$Partial path="api_settings.mdx" variables={{ "framework": "{{ .framework }}", "tab": "{{ .tab }}" }}
+/>
@@ -32,6 +32,21 @@ There are 4 types of API keys that can be used with Supabase:

 </Admonition>

+<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.
+
+</Admonition>
+
+## Where to find keys
+
+You can find API keys in a couple of different places.
+
+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.
+
 ## `anon` and publishable keys

 The `anon` and publishable keys secure the public components of your application. Public components run in environments where it is impossible to secure any secrets. These include:
@@ -52,20 +52,26 @@ create table

 Every Supabase project has a unique API URL. Your API is secured behind an API gateway which requires an API Key for every request.

-1. Go to the [Settings](/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.
+{/* TODO: Further consolidate partial */}

-<video width="99%" muted playsInline controls={true}>
-  <source
-    src="https://xguihxuzqibwxjnimxev.supabase.co/storage/v1/object/public/videos/docs/api/api-url-and-key.mp4"
-    type="video/mp4"
-  />
-</video>
+To do this, you need to get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/_?showConnect=true).
+
+<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.
+
+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.
+
+</Admonition>
+
+[Read the API keys docs](/docs/guides/api/api-keys) for a full explanation of all key types and their uses.

 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 key to be passed through an `apikey` header.

 ## Using the API

@@ -52,9 +52,11 @@ 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 Key](/dashboard/project/_/settings/api).
+        Rename `.env.example` to `.env.local` and populate with your Supabase connection variables:

-    <$Partial path="api_settings_steps.mdx" />
+        <ProjectConfigVariables variable="url" />
+        <ProjectConfigVariables variable="publishable" />
+        <ProjectConfigVariables variable="anon" />

    </StepHikeCompact.Details>

@@ -65,6 +67,8 @@ hideToc: true
      NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... or anon key
      ```

+      <$Partial path="api_settings_steps.mdx" />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -66,7 +66,9 @@ hideToc: true

    Create a helper file `lib/supabase.ts` that exports a Supabase client using your Project URL and key.

-    <$Partial path="api_settings_steps.mdx" />
+    <ProjectConfigVariables variable="url" />
+    <ProjectConfigVariables variable="publishable" />
+    <ProjectConfigVariables variable="anon" />

    </StepHikeCompact.Details>
    <StepHikeCompact.Code>
@@ -106,6 +108,7 @@ hideToc: true
        })
      }
      ```
+      <$Partial path="api_settings_steps.mdx" />

    </StepHikeCompact.Code>

@@ -63,9 +63,12 @@ hideToc: true
  <StepHikeCompact.Step step={4}>
    <StepHikeCompact.Details title="Declare Supabase Environment Variables">

-    Create `.env.local` and populate with your project's URL and Key.
+        Rename `.env.example` to `.env.local` and populate with your Supabase connection variables:
+
+        <ProjectConfigVariables variable="url" />
+        <ProjectConfigVariables variable="publishable" />
+        <ProjectConfigVariables variable="anon" />

-    <$Partial path="api_settings_steps.mdx" />

    </StepHikeCompact.Details>

@@ -75,6 +78,7 @@ hideToc: true
      VITE_SUPABASE_URL=your-project-url
      VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY=sb_publishable_... or anon key
      ```
+      <$Partial path="api_settings_steps.mdx" />

    </StepHikeCompact.Code>

@@ -16,7 +16,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": "exporeactnative", "tab": "mobiles" }} />

 ## Building the app

@@ -832,7 +832,7 @@ For more information, follow the [Supabase Login with Apple](/docs/guides/auth/s
  </TabPanel>

  <TabPanel id="react-apple-signin-auth" label="Web">
-    
+
    #### Prerequisites

    Before proceeding, as per the mobile options you need an Apple Service ID. To obtain it you can follow the [Invertase Initial Setup Guide](https://github.com/invertase/react-native-apple-authentication/blob/main/docs/INITIAL_SETUP.md) and the [Invertase Android Setup Guide](https://github.com/invertase/react-native-apple-authentication/blob/main/docs/ANDROID_EXTRA.md) mentioned in the Invertase tab.
@@ -45,6 +45,8 @@ Create a `.env.local` file in the project root directory. In the file, set the p
 <ProjectConfigVariables variable="publishable" />
 <ProjectConfigVariables variable="anon" />

+<$Partial path="api_settings_steps.mdx" />
+
 <Tabs scrollable size="small" type="underlined" defaultActiveId="nextjs" queryGroup="framework">

 <TabPanel id="nextjs" label="Next.js">
@@ -79,6 +79,8 @@ hideToc: true
      }
      ```

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "flutter", "tab": "mobiles" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -61,6 +61,9 @@ hideToc: true
      cp .env.example .env
      ```

+{/* TODO: Not ideal for frameworks that have no entry in Connect */}
+<$Partial path="api_settings_steps.mdx" variables={{ "framework": "", "tab": "frameworks" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -58,6 +58,8 @@ hideToc: true
      )
      ```

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "swift", "tab": "mobiles" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -98,6 +98,8 @@ hideToc: true
      ...
      ```

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "androidkotlin", "tab": "mobiles" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -58,6 +58,8 @@ hideToc: true

      </$CodeTabs>

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "nextjs", "tab": "frameworks" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -84,6 +84,7 @@ hideToc: true
        ```

      </$CodeTabs>
+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "nuxt", "tab": "frameworks" }} />

    </StepHikeCompact.Code>

@@ -74,6 +74,8 @@ hideToc: true

      </$CodeTabs>

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "react", "tab": "frameworks" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -100,6 +100,7 @@ hideToc: true
        },
      });
      ```
+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "refine", "tab": "frameworks" }} />

    </StepHikeCompact.Code>

@@ -72,6 +72,8 @@ hideToc: true

      </$CodeTabs>

+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "solidjs", "tab": "frameworks" }} />
+
    </StepHikeCompact.Code>

  </StepHikeCompact.Step>
@@ -72,6 +72,7 @@ hideToc: true
        ```

      </$CodeTabs>
+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "sveltekit", "tab": "frameworks" }} />

    </StepHikeCompact.Code>

@@ -73,6 +73,7 @@ hideToc: true
        ```

      </$CodeTabs>
+      <$Partial path="api_settings_steps.mdx" variables={{ "framework": "vue", "tab": "frameworks" }} />

    </StepHikeCompact.Code>

@@ -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": "ionicangular", "tab": "mobiles" }} />

 ## Building the app

@@ -14,7 +14,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": "exporeactnative", "tab": "mobiles" }} />

 ## Building the app

@@ -14,7 +14,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": "flutter", "tab": "mobiles" }} />

 ## Building the app

@@ -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": "ionicangular", "tab": "mobiles" }} />

 ## Building the app

@@ -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": "ionicreact", "tab": "mobiles" }} />

 ## Building the app

@@ -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": "vuejs", "tab": "frameworks" }} />

 ## Building the app

@@ -17,7 +17,7 @@ If you get stuck while working through this guide, refer to the [full example on

 </Admonition>

-<$Partial path="kotlin_project_setup.mdx" />
+<$Partial path="kotlin_project_setup.mdx" variables={{ "framework": "androidkotlin", "tab": "mobiles" }} />

 ## Building the app

@@ -14,7 +14,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": "nextjs", "tab": "frameworks" }} />

 ## Building the app

@@ -14,7 +14,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": "nuxt", "tab": "frameworks" }} />

 ## Building the app

@@ -14,7 +14,7 @@ If you get stuck while working through this guide, refer to the [full example on

 </Admonition>

-<$Partial path="project_setup.mdx" variables={{ "framework": "React" }} />
+<$Partial path="project_setup.mdx" variables={{ "framework": "react", "tab": "frameworks" }} />

 ## Building the app

@@ -39,7 +39,7 @@ Instead, we'll rely on the Supabase client to do some of the work on the **`web`
 That means you will want to refrain from running any `yarn rw prisma migrate` commands and also double check your build commands on deployment to ensure Prisma won't reset your database. Prisma currently doesn't support cross-schema foreign keys, so introspecting the schema fails due
 to how your Supabase `public` schema references the `auth.users`.

-<$Partial path="project_setup.mdx" />
+<$Partial path="project_setup.mdx" variables={{ "framework": "", "tab": "frameworks" }} />

 ## Building the app

@@ -25,7 +25,7 @@ It is possible to customize the `authProvider` for Supabase and as we'll see bel

 </Admonition>

-<$Partial path="project_setup.mdx" />
+<$Partial path="project_setup.mdx" variables={{ "framework": "refine", "tab": "frameworks" }} />

 ## Building the app

@@ -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": "solidjs", "tab": "frameworks" }} />

 ## Building the app

@@ -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": "sveltekit", "tab": "frameworks" }} />

 ## Building the app

@@ -73,7 +73,7 @@ meta="name=src/lib/Auth.svelte"
 After a user is signed in, allow them to edit their profile details and manage their account.
 Create a new component for that called `Account.svelte`.

-<$CodeSample  
+<$CodeSample
 path="/user-management/svelte-user-management/src/lib/Account.svelte"
 lines={[[1, 4], [7, 11], [14, 33], [34,53], [55,73], [75,-1]]}
 meta="src/lib/Account.svelte"
@@ -121,7 +121,7 @@ meta="name=src/lib/Avatar.svelte"

 And then you can add the widget to the Account page:

-<$CodeSample  
+<$CodeSample
 path="/user-management/svelte-user-management/src/lib/Account.svelte"
 lines={[[1,1], [5,5], [71,73], [74,74], [92,-1]]}
 meta="src/lib/Account.svelte"
@@ -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": "sveltekit", "tab": "frameworks" }} />

 ## Building the app

@@ -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": "swift", "tab": "mobiles" }} />

 ## Building the app

@@ -14,7 +14,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": "vuejs", "tab": "frameworks" }} />

 ## Building the app

@@ -33,7 +33,20 @@ You can use the Supabase client libraries to receive Broadcast messages.

 ### Initialize the client

-Go to your Supabase project's [API Settings](/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.
+{/* TODO: Further consolidate partial */}
+
+Get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/_?showConnect=true).
+
+<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.
+
+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.
+
+</Admonition>

 <Tabs
  scrollable
@@ -31,7 +31,20 @@ The complete presence state returned by `presenceState()` looks like this:

 ### Initialize the client

-Go to your Supabase project's [API Settings](/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.
+{/* TODO: Further consolidate partial */}
+
+Get the Project URL and key from [the project's **Connect** dialog](/dashboard/project/_?showConnect=true).
+
+<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.
+
+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.
+
+</Admonition>

 <Tabs
  scrollable