diff --git a/apps/docs/content/_partials/api_keys_deprecation.mdx b/apps/docs/content/_partials/api_keys_deprecation.mdx index 3b065fb6e6d..994ccb70cdc 100644 --- a/apps/docs/content/_partials/api_keys_deprecation.mdx +++ b/apps/docs/content/_partials/api_keys_deprecation.mdx @@ -2,9 +2,6 @@ Supabase is deprecating the `anon` and `service_role` keys by the end of 2026. Use the publishable (`sb_publishable_xxx`) and secret (`sb_secret_xxx`) keys instead. For the reasoning behind the change, see [the announcement on GitHub](https://github.com/orgs/supabase/discussions/29260). -In most cases you can get keys from your project's [**Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}). To pick a specific key, open the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. - -- **For publishable and secret keys**, open the **API Keys** tab. If you don't have a publishable key, select **Create new API Keys**. Copy the **Publishable key** for client-side operations, and a key from **Secret keys** for server-side operations. -- **For legacy keys**, open the **Legacy API Keys** tab. Copy the `anon` key for client-side operations and the `service_role` key for server-side operations. +In most cases you can get keys from your project's [**Connect** dialog](/dashboard/project/\_?showConnect=true&connectTab={{ .tab }}&framework={{ .framework }}). For every way to retrieve a key, including the CLI and the Management API, refer to [Find your keys](/docs/guides/getting-started/api-keys#find-your-keys). diff --git a/apps/docs/content/guides/getting-started/api-keys.mdx b/apps/docs/content/guides/getting-started/api-keys.mdx index 58ef619a97b..78be04b482c 100644 --- a/apps/docs/content/guides/getting-started/api-keys.mdx +++ b/apps/docs/content/guides/getting-started/api-keys.mdx @@ -10,7 +10,7 @@ This guide covers: - [Which key do you use?](#which-key-do-you-use) answers that in one table. - [How API keys work](#how-api-keys-work) explains what each key type is and which Postgres role it maps to. -- [Find and use your keys](#find-and-use-your-keys) covers getting a key out of the Dashboard and rotating one that leaked. +- [Find and use your keys](#find-and-use-your-keys) covers the ways to retrieve a key and how to rotate one that leaked. - [Security reference](#security-reference) lists what publishable keys don't protect against, how to handle secret keys, and the known limitations. ## Which key do you use? @@ -106,8 +106,91 @@ Secret keys improve on the old JWT-based `service_role` key, and we recommend th ### Find your keys -1. Open your project's [**Connect** dialog](/dashboard/project/_?showConnect=true). It shows the keys for the framework you select, which is the fastest path for most setups. -2. To pick a specific key, or to see every key your project has, open the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. +Pick the path that matches where you are working. + +Every path below reads keys that already exist. If your project has no publishable or secret key yet, create them first in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard. + + + + +Use the Dashboard when you are setting up a project by hand. It needs nothing but a signed-in session. + +1. Open your project's [**Connect** dialog](/dashboard/project/_?showConnect=true). It shows the URL and publishable key for the framework you select, ready to paste into `.env`. +2. To pick a specific key, or to see every key your project has, open the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard instead. +3. Copy each value into your project's `.env` file. + + + + +Use the CLI to script setup, or to read the keys for a preview branch. This path needs the Supabase CLI, so [install it](/docs/guides/local-development/cli/getting-started#installing-the-supabase-cli) first. + +1. Sign in, if you haven't already: + + ```bash + supabase login + ``` + +2. Find the project ref, if you don't know it: + + ```bash + supabase projects list + ``` + +3. List the keys for that project: + + ```bash + supabase projects api-keys --project-ref your-project-ref + ``` + +Pass the branch's own project ref to read the keys for a preview branch. A branch has its own keys, and the command returns the linked project's keys when you omit the flag. + + + + +Use the Management API to fetch keys from your own tooling, such as a deploy script or an internal provisioning service. + +Authenticate with a [personal access token](/dashboard/account/tokens). An OAuth application needs the `secrets:read` scope, and a fine-grained token needs the `api_gateway_keys_read` permission. Without either, the request returns 403 Forbidden. + +```bash +export PROJECT_REF="your-project-ref" +export SUPABASE_ACCESS_TOKEN="your-personal-access-token" + +curl -X GET "https://api.supabase.com/v1/projects/$PROJECT_REF/api-keys?reveal=true" \ + -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \ + | jq '.[] | {name, type}' +``` + +`reveal=true` includes the key values in the response, and this `jq` filter drops them again so they stay out of your terminal. Write the values straight into your secret store rather than printing them, because anything on standard output lands in your CI logs. See [Get project API keys](/docs/reference/api/v1-get-project-api-keys) for the full response. + + + + +A local stack mints its own keys. They are unrelated to your hosted project's keys, so a local key never grants access to your hosted data. + +This path needs the Supabase CLI and a container runtime. See [Running a local Supabase project](/docs/guides/local-development/cli/getting-started#running-a-local-supabase-project) for both. + +1. Start the stack: + + ```bash + supabase start + ``` + + The publishable and secret keys are in the output, under **Authentication Keys**. + +2. Print them again at any time while the stack is running: + + ```bash + supabase status + ``` + + + ### Rotate a leaked or compromised key [#leaked-key]