dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure the API keys guide by information type (#49796)

Browse Source 
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update. Restructure, mostly moved lines, plus a tense fix in a
shared partial.

## What is the current behavior?

Context, procedure, and reference material are interleaved, so
background reading interrupts the action path.

- The page never states which key to use as an answer. You infer it from
a five-column reference table.
- Finding a key is a fragment inside an admonition, placed above the
page's own definition of an API key.
- Rotating a leaked key, the only procedure on the page, is the last H3.
- The "Changes to API keys" notice narrates a past change in future
tense, and "They will be deprecated" has no antecedent in its paragraph.

## What is the new behavior?

Group the guide into context, procedure, and reference sections, per
CONTRIBUTING § Guides on mixed information types.

- Lead with "Which key do you use?", a decision table keyed on where the
code runs. Section navigation sits directly below the intro.
- Collect the conceptual sections under "How API keys work" and give
publishable and secret keys parallel headings.
- Promote both procedures into "Find and use your keys". Rotation is now
an ordered procedure.
- Move the enumerated secret key rules into "Security reference",
grouped under bold labels by the kind of mistake each prevents, and
leave a short danger admonition where secret keys are introduced.
- Promote the five-sentence coexistence admonition to its own section.
Admonitions are for short warnings.
- Rewrite the shared deprecation partial for timeless documentation:
present tense, no dangling "They", no "now". The partial renders on five
pages.
- Pin a stable anchor on the rotation heading and update the one inbound
link, in the rotating-anon-service-and-jwt-secrets troubleshooting
entry.
- Align link text across docs for this guide. Twenty-one links pointed
at it under fourteen labels, including two that named the wrong
destination. Rule: when a link means the guide, the text is "API keys";
when it means a specific key or section, the specific text stays. Twelve
now share "API keys", up from three.

Review with `git diff --color-moved=zebra`.

## Additional context

PR 2 of 4. Base is #49795. Includes the link-text alignment previously
opened as #49866.

## Manual testing

1. Open the API keys guide on the deploy preview.
2. Check the table of contents. It shows three groups: How API keys
work, Find and use your keys, Security reference.
3. Open the rotating-anon-service-and-jwt-secrets troubleshooting entry
and follow "Rotate a leaked or compromised key" under Further readings.
It lands on the renamed heading.
4. Open the Realtime Broadcast guide and check the "Changes to API keys"
notice. It reads in present tense there too.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Documentation**
- Updated API key guidance to explain the transition from legacy `anon`
and `service_role` keys to publishable and secret keys by the end of
2026.
- Reorganized the API keys guide with clearer key-selection guidance,
security recommendations, usage examples, and rotation steps.
- Updated troubleshooting references to point to the revised leaked-key
rotation guidance.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Miranda Limonczenko authored and GitHub committed 2026-09-01 14:40:54 -07:00
1 parent 2f31010a18
commit d7f1a44e53
10 files changed
+121 -80
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/docs/content/_partials/api_keys_deprecation.mdx
+4 -6
View File
@@ -1,12 +1,10 @@
<Admonition type="deprecation" title="Changes to API keys">
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).
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).
**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 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.
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.
- **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.
</Admonition>
apps/docs/content/_partials/api_settings.mdx
+1 -1
View File
@@ -7,6 +7,6 @@ To interact with data in database tables, you use the client libraries that wrap
<Admonition type="note">
[Read the API keys docs](/docs/guides/getting-started/api-keys) for a full explanation of all key types, their uses, and where to find them.
See [API keys](/docs/guides/getting-started/api-keys) for a full explanation of all key types, their uses, and where to find them.
</Admonition>
apps/docs/content/_partials/metrics_access.mdx
+1 -1
View File
@@ -22,7 +22,7 @@ className="rounded-lg border border-foreground/10 bg-surface-100 text-foreground
3. Authenticate with HTTP Basic Auth:
- **Username**: `service_role`
- **Password**: a **Secret API key** (`sb_secret_...`). You can create/copy it in [**Project Settings → API Keys**](/dashboard/project/_/settings/api-keys). For more context, see [Understanding API keys](/docs/guides/getting-started/api-keys).
- **Password**: a **Secret API key** (`sb_secret_...`). You can create/copy it in [**Project Settings → API Keys**](/dashboard/project/_/settings/api-keys). For more context, see [API keys](/docs/guides/getting-started/api-keys).
To test locally, run `curl` with your Secret API key:
apps/docs/content/guides/api/creating-routes.mdx
+1 -1
View File
@@ -68,7 +68,7 @@ To do this, you need to get the Project URL and key from [the project's **Connec
<$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.
See [API keys](/docs/guides/getting-started/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`
apps/docs/content/guides/auth/signing-keys.mdx
+1 -1
View File
@@ -214,7 +214,7 @@ Finally, you can use your newly minted JWT by setting the `Authorization: Bearer
<Admonition type="note">
A separate `apikey` header is required to access your project's APIs. This can be a [publishable, secret or the legacy `anon` or `service_role` keys](/docs/guides/getting-started/api-keys). Using your minted JWT is not possible in this header.
A separate `apikey` header is required to access your project's APIs. Use a publishable or secret key, or a legacy `anon` or `service_role` key. See [API keys](/docs/guides/getting-started/api-keys). Using your minted JWT is not possible in this header.
</Admonition>
apps/docs/content/guides/getting-started/api-keys.mdx
+106 -63
View File
@@ -1,16 +1,38 @@
---
id: 'api-keys'
title: 'Understanding API keys'
title: 'API keys'
description: "First-layer protection for your project's data"
---
Supabase gives you fine-grained control over which application components are allowed to access your project through API keys.
Every request to your Supabase project carries an API key. The key identifies what is calling your project: a web page, a mobile app, a server, or an Edge Function. [Supabase Auth](/docs/guides/auth) identifies who is calling, when someone is signed in.
<Admonition type="note" title="Looking for your API Keys?">
This guide covers:
In most cases, you can get the correct key from your project's [**Connect** dialog](/dashboard/project/_?showConnect=true). To pick a specific key, open the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard.
- [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.
- [Security reference](#security-reference) lists what publishable keys don't protect against, how to handle secret keys, and the known limitations.
</Admonition>
## Which key do you use?
Pick the key by asking where the code runs.
| Where the code runs | Use this key | Because |
| ----------------------------------------------------- | --------------- | --------------------------------------------------------------------- |
| Anything you ship: browser, mobile app, CLI, script | Publishable key | Anyone can read it, so it only reaches what Row Level Security allows |
| Anything you control: server, Edge Function, cron job | Secret key | It bypasses Row Level Security, so it must never leave your control |
Think of your project's data as a building. The publishable key is taped to the front door, and it only opens the lobby. The secret key is the master key, and it stays in your pocket.
With the key chosen, go to [Find and use your keys](#find-and-use-your-keys) to get its value, or to [How API keys work](#how-api-keys-work) for what that key authorizes and which Postgres role it maps to.
<$Partial path="api_keys_deprecation.mdx" />
## How API keys work
### What an API key identifies
An API key authenticates an application component to give it access to Supabase services. An application component might be a web page, a mobile app, or a server. An API key doesn't distinguish between users but between applications.
API keys provide the first layer of authentication for data access. Supabase Auth builds on top of that. This table covers the difference:
@@ -19,9 +41,7 @@ API keys provide the first layer of authentication for data access. Supabase Aut
| API keys | What is accessing the project? | A web page, a mobile app, a server, or an Edge Function |
| [Supabase Auth](/docs/guides/auth) | Who is accessing the project? | An individual signed-in user |
## Overview
An API key authenticates an application component to give it access to Supabase services. An application component might be a web page, a mobile app, or a server. An API key doesn't distinguish between users but between applications.
### Key types
Supabase supports four types of API keys:
@@ -32,15 +52,15 @@ Supabase supports four types of API keys:
| <span className="whitespace-nowrap!">`anon`</span> | JWT (long-lived) | Low | <span className="whitespace-nowrap!">Platform, CLI</span> | Legacy version of publishable keys. |
| <span className="whitespace-nowrap!">`service_role`</span> | JWT (long-lived) | Elevated | <span className="whitespace-nowrap!">Platform, CLI</span> | Legacy version of secret keys. |
<Admonition type="note" title="Creating new keys doesn't revoke your legacy keys">
### Legacy `anon` and `service_role` keys
Both key types work simultaneously. Creating publishable and secret keys adds them alongside your existing `anon` and `service_role` keys without affecting them, so your legacy keys keep working. They remain valid until you disable them in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard, which is a separate step. See [Migrating to new API keys](/docs/guides/getting-started/migrating-to-new-api-keys) for the full process.
Creating publishable and secret keys doesn't revoke your legacy keys. Both key systems work at the same time.
</Admonition>
Creating a publishable or secret key adds it alongside your existing `anon` and `service_role` keys without affecting them, so your legacy keys keep working. They stay valid until you disable them in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard, which is a separate step.
<$Partial path="api_keys_deprecation.mdx" />
See [Migrating to new API keys](/docs/guides/getting-started/migrating-to-new-api-keys) for the full process.
## Publishable keys
### Publishable keys and public components
Publishable keys identify the public components of your application. Public components run in environments where you can't keep a secret. These include:
@@ -51,7 +71,7 @@ Publishable keys identify the public components of your application. Public comp
These environments are always considered public because anyone can retrieve the key from the source code or build artifacts.
### Interaction with Supabase Auth
### Postgres roles and Row Level Security
Using a publishable key doesn't mean your user is anonymous. Your application authenticates with the publishable key while your user authenticates separately through Supabase Auth with their own JWT:
@@ -60,7 +80,49 @@ Using a publishable key doesn't mean your user is anonymous. Your application au
| Publishable key | No | `anon` |
| Publishable key | Yes | `authenticated` |
### Security considerations
### Secret keys and elevated access
Unlike publishable keys, secret keys allow elevated access to your project's data. Use them only in secure, developer-controlled components of your application, such as:
- Servers that run their own authorization checks, such as Edge Functions, microservices, and web servers.
- Periodic jobs, queue processors, topic subscribers.
- Admin and back-office tools that run authorization checks first.
- Data processing pipelines, such as for analytics, reports, backups, or database synchronization.
<Admonition type="danger" title="A leaked secret key exposes all of your project's data">
A secret key bypasses every Row Level Security policy you have. Never put one in a browser, a shipped application, or source control. For the full list of places a secret key must never go, see [Handling secret keys safely](#handling-secret-keys-safely).
</Admonition>
Secret keys authorize access to your project's data through the built-in `service_role` Postgres role. By design, this role has full access to your project's data. It also has the [`BYPASSRLS` attribute](https://www.postgresql.org/docs/current/ddl-rowsecurity.html#:~:text=BYPASSRLS), so it skips every Row Level Security policy you attach.
Secret keys improve on the old JWT-based `service_role` key, and we recommend them wherever possible. They add checks that prevent misuse:
- A secret key doesn't work in a browser. Supabase matches on the `User-Agent` header and returns HTTP 401 Unauthorized.
- A project doesn't need any secret keys if nothing uses them.
## Find and use your keys
### 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.
### Rotate a leaked or compromised key [#leaked-key]
This procedure covers both a leaked secret key and a leaked `service_role` key.
Don't rush. Fix the root cause of the leak before you rotate anything. The [OWASP Risk Rating Methodology](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) helps you judge the severity of the incident and plan your next steps.
1. Create a new secret key in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard.
2. Replace the compromised key with the new one everywhere your application uses it. If the compromised key is a JWT-based `service_role` key, replace it with the new secret key.
3. Confirm that every component now uses the new key.
4. Retire the compromised key. Delete a secret key, which can't be undone, so don't start until step 3 is done. For a legacy `anon` or `service_role` key, deactivate the legacy keys in the same Dashboard section instead. Deactivation is reversible, so you can re-enable them if you find a client you missed.
## Security reference
### What publishable keys don't protect against
Publishable keys aren't intended to protect against the following, because anyone can retrieve a key from a public component:
@@ -77,62 +139,43 @@ When you use a publishable key, Postgres guards access to your project's data th
Your project's [Security Advisor](/dashboard/project/_/advisors/security) checks for common security problems with the built-in Postgres roles. Review each finding carefully before you dismiss it.
## What secret keys allow access to
### Handling secret keys safely
Unlike publishable keys, secret keys allow elevated access to your project's data. Use them only in secure, developer-controlled components of your application, such as:
Exposing a secret key puts all of your project's data at risk. The rules below are grouped by the kind of mistake they prevent.
- Servers that run their own authorization checks, such as Edge Functions, microservices, and web servers.
- Periodic jobs, queue processors, topic subscribers.
- Admin and back-office tools that run authorization checks first.
- Data processing pipelines, such as for analytics, reports, backups, or database synchronization.
**Where a secret key must never appear**
<Admonition type="caution">
- A web page, a public document, source code, or a bundled mobile, desktop, or CLI package.
- A browser, even on `localhost`.
Exposing a secret key puts all of your project's data at risk. Don't:
**How a secret key must never travel**
- Add a secret key to a web page, a public document, source code, or a bundled mobile, desktop, or CLI package.
- Send one over chat, email, or SMS.
- Use one in a browser, even on `localhost`.
- Pass one in a URL or query parameter, because those are often logged.
- Pass one in a request header before you sanitize your logs.
- Log even an apparently invalid API key. A typo today can reveal the real key later.
- Reveal, copy, or use one on a device you don't own or control, or on a device without full-disk encryption. Public computers and borrowed laptops both count.
- Over chat, email, or SMS.
- In a URL or a query parameter, because those are often logged.
- In a request header, until you have log sanitization in place.
- Over plain HTTP, or to any host other than your project's Supabase endpoint.
**What must never be written down**
- Don't log a key, even one that looks invalid. A typo today can reveal the real key later.
- If you must record a key, log no more than 6 characters from the random part after its prefix.
- To record which key was used, store a SHA256 hash of it instead.
**Storing and sharing a secret key**
- Work with secret keys only on computers you fully own or control.
- Encrypt keys stored in files or environment variables.
- Keep keys out of source control, including CI scripts. Use the tool's own secrets storage instead.
- Share keys through an encrypted transfer tool, such as the one in your password manager. Better still, have the other person read the key from the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard.
**Limiting the damage of a leak**
- Use a separate secret key for each backend component. If one component leaks its key, you only rotate that one.
- Delete a leaked key immediately. The browser block returns HTTP 401 Unauthorized, but an attacker can still use the key from other tools.
Handle secret keys using [secure coding practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/stable-en/).
</Admonition>
Secret keys authorize access to your project's data through the built-in `service_role` Postgres role. By design, this role has full access to your project's data. It also has the [`BYPASSRLS` attribute](https://www.postgresql.org/docs/current/ddl-rowsecurity.html#:~:text=BYPASSRLS), so it skips every Row Level Security policy you attach.
Secret keys improve on the old JWT-based `service_role` key, and we recommend them wherever possible. They add checks that prevent misuse:
- A secret key doesn't work in a browser. Supabase matches on the `User-Agent` header and returns HTTP 401 Unauthorized.
- A project doesn't need any secret keys if nothing uses them.
### Best practices for handling secret keys
Follow these guidelines when you work with secret keys:
- Always work with secret keys on computers you fully own or control.
- Share keys through an encrypted transfer tool, such as the one in your password manager. Better still, have the other person read the key from the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard.
- Encrypt keys stored in files or environment variables.
- Keep keys out of source control, including CI scripts. Use the tool's own secrets storage instead.
- Use a separate secret key for each backend component. If one component leaks its key, you only rotate that one.
- Delete a leaked key immediately. The browser block returns HTTP 401 Unauthorized, but an attacker can still use the key from other tools.
- Log no more than 6 characters if you must record a key, counted from the random part after its prefix.
- Store a SHA256 hash if you need to record which key was used.
### What to do if a secret key or `service_role` has been leaked or compromised?
Don't rush. Fix the root cause of the leak first, before you rotate anything. The [OWASP Risk Rating Methodology](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) helps you judge the severity of the incident and plan your next steps.
To rotate a secret key, create a new one in the [**Settings > API Keys**](/dashboard/project/_/settings/api-keys/) section of the Dashboard, then replace the compromised key with the new one everywhere your application uses it. Once every component uses the new key, delete the compromised one.
Deleting a secret key is irreversible.
If you still use the JWT-based `service_role` key, replace it with a new secret key. Follow the same steps as for rotating a secret key.
## Known limitations and compatibility differences
### Known limitations
Publishable and secret keys aren't JWTs, which creates a few compatibility differences to plan for:
apps/docs/content/guides/getting-started/migrating-to-new-api-keys.mdx
+1 -1
View File
@@ -17,7 +17,7 @@ The migration maps onto your existing keys:
| `anon` | Publishable key | Browsers, mobile and desktop apps, CLIs, public source |
| `service_role` | Secret key | Servers, Edge Functions, workers, other backend code |
For a full explanation of each key type, read [the Understanding API keys guide](/docs/guides/getting-started/api-keys).
For a full explanation of each key type, see [API keys](/docs/guides/getting-started/api-keys).
## Step 1: Create the new API keys
apps/docs/content/guides/self-hosting/self-hosted-auth-keys.mdx
+3 -3
View File
@@ -4,7 +4,7 @@ description: 'Configure new API keys and ES256 asymmetric authentication for sel
subtitle: 'Configure new API keys and ES256 asymmetric authentication for self-hosted Supabase.'
---
You can configure self-hosted Supabase to use the [new API keys](/docs/guides/getting-started/api-keys) alongside the legacy API keys (`ANON_KEY` and `SERVICE_ROLE_KEY` HS256-signed JWTs).
You can configure self-hosted Supabase to use the [publishable and secret API keys](/docs/guides/getting-started/api-keys) alongside the legacy API keys (`ANON_KEY` and `SERVICE_ROLE_KEY` HS256-signed JWTs).
## Before you begin
@@ -77,7 +77,7 @@ sh run.sh recreate
### New API keys format
The new API keys use the [same format](/docs/guides/getting-started/api-keys) as the Supabase platform:
These keys use the same format as [API keys](/docs/guides/getting-started/api-keys) on the Supabase platform:
```
sb_publishable_<22-char-random>_<8-char-checksum>
@@ -204,7 +204,7 @@ For details on how the API gateway routes and authenticates requests, see the [E
## Additional resources
- [Understanding API keys](/docs/guides/getting-started/api-keys) - How API keys work on the Supabase platform
- [API keys](/docs/guides/getting-started/api-keys) - How API keys work on the Supabase platform
- [Auth architecture](/docs/guides/auth/architecture) - How the Auth service handles authentication and token signing
- [JWT Signing Keys](/docs/guides/auth/signing-keys) - Best practices on managing keys used by Supabase Auth to create and verify JSON Web Tokens
- [JSON Web Token (JWT)](/docs/guides/auth/jwts) - How to best use JSON Web Tokens with Supabase
apps/docs/content/troubleshooting/rotating-anon-service-and-jwt-secrets-1Jq6yd.mdx
+2 -2
View File
@@ -9,7 +9,7 @@ database_id = "caa72a34-696c-47c6-8976-e50cf7fb396e"
<Admonition type="deprecation">
This troubleshooting guide is about rotating **Legacy anon, service_role API keys**. We are deprecating Legacy, and recommend migrating to New API keys. To learn more about API keys, refer to [the API documentation](/docs/guides/getting-started/api-keys).
This troubleshooting guide is about rotating **Legacy anon, service_role API keys**. We are deprecating Legacy, and recommend migrating to New API keys. To learn more about API keys, refer to [API keys](/docs/guides/getting-started/api-keys).
</Admonition>
@@ -38,5 +38,5 @@ If you have migrated to new symmetric JWT signing keys:
## Further readings
- [What to do if a secret key or service_role has been leaked or compromised?](/docs/guides/getting-started/api-keys#what-to-do-if-a-secret-key-or-servicerole-has-been-leaked-or-compromised)
- [Rotate a leaked or compromised key](/docs/guides/getting-started/api-keys#leaked-key)
- [JWT Signing Keys](/docs/guides/auth/signing-keys)
apps/docs/content/troubleshooting/why-is-my-service-role-key-client-getting-rls-errors-or-not-returning-data-7_1K9z.mdx
+1 -1
View File
@@ -10,7 +10,7 @@ database_id = "677f0a69-e454-4718-ad92-91053d40c085"
<Admonition type="deprecation">
This troubleshooting guide is about rotating **Legacy anon, service_role API keys**. We are deprecating the Legacy API keys, and recommend migrating to New API keys. To learn more about API
keys, refer to [the API documentation](/docs/guides/getting-started/api-keys).
keys, refer to [API keys](/docs/guides/getting-started/api-keys).
</Admonition>