From 8a1adbbd1479f45ffe943039966c798f0239b4b1 Mon Sep 17 00:00:00 2001
From: "Andrey A." <56412611+aantti@users.noreply.github.com>
Date: Fri, 4 Sep 2026 18:34:17 +0200
Subject: [PATCH 1/2] docs(self-hosted): use opaque api keys in self-hosted
 how-to guides (#50000)

---
 .../guides/self-hosting/self-hosted-envoy.mdx |  2 +-
 .../guides/self-hosting/self-hosted-oauth.mdx |  6 +--
 .../self-hosting/self-hosted-saml-sso.mdx     | 39 +++++++------------
 3 files changed, 19 insertions(+), 28 deletions(-)

diff --git a/apps/docs/content/guides/self-hosting/self-hosted-envoy.mdx b/apps/docs/content/guides/self-hosting/self-hosted-envoy.mdx
index f4369c1fd3d47..627a95010d3b3 100644
--- a/apps/docs/content/guides/self-hosting/self-hosted-envoy.mdx
+++ b/apps/docs/content/guides/self-hosting/self-hosted-envoy.mdx
@@ -19,7 +19,7 @@ Envoy is registered as the `api-gw` service and also exposes `envoy` and `kong`
 Confirm the gateway is routing requests and enforcing API keys:
 
 ```sh
-curl -i -H "apikey: your-service-role-key" http://<your-domain>/rest/v1/
+curl -i -H "apikey: your-supabase-secret-key" http://<your-domain>/rest/v1/
 ```
 
 A `200 OK` response from PostgREST confirms the gateway is up. A `401 Unauthorized` without the `apikey` header confirms enforcement is active.
diff --git a/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx
index 66e4872deb9c6..210e04635cf9e 100644
--- a/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx
+++ b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx
@@ -99,7 +99,7 @@ sh run.sh recreate auth
 Check that the provider is enabled:
 
 ```sh
-curl -H 'apikey: your-anon-key' https://<your-domain>/auth/v1/settings
+curl -H 'apikey: your-supabase-publishable-key' https://<your-domain>/auth/v1/settings
 ```
 
 The response should include your provider under `external`:
@@ -350,9 +350,9 @@ You can test OAuth with the following minimal HTML page:
     <script>
       document.addEventListener('DOMContentLoaded', function () {
         const SUPABASE_URL = 'https://<your-domain>'
-        const SUPABASE_ANON_KEY = 'your-anon-key'
+        const SUPABASE_PUBLISHABLE_KEY = 'your-supabase-publishable-key'
 
-        const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
+        const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY)
 
         const button = document.getElementById('loginBtn')
 
diff --git a/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx b/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx
index 15054f368e0c1..3c90070581112 100644
--- a/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx
+++ b/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx
@@ -22,7 +22,7 @@ You need:
 - A running self-hosted Supabase instance (see the [setup guide](/docs/guides/self-hosting/docker))
 - Open SSL installed (for key generation)
 - Your IdP's SAML metadata URL or metadata XML
-- The `SERVICE_ROLE_KEY` from your `.env` file (needed for admin API calls)
+- Your project's secret key, `SUPABASE_SECRET_KEY`, from your `.env` file (needed for admin API calls)
 - `API_EXTERNAL_URL` set to the publicly-accessible URL of your Supabase Auth service (e.g., `https://<your-domain>/auth/v1`). Used as the base for constructing the SAML Service Provider entity ID and ACS endpoint URL
 
 ## How SAML SSO works in Supabase
@@ -156,7 +156,7 @@ Key values in the metadata:
 
 ## Step 6: Register an identity provider
 
-Use the Auth admin API to register your IdP. You need the `SERVICE_ROLE_KEY` for authentication.
+Use the Auth admin API to register your IdP. You need your project's secret key, `SUPABASE_SECRET_KEY`, for authentication.
 
 ### Option A: Register with a metadata URL (recommended)
 
@@ -164,9 +164,8 @@ If your IdP provides a metadata URL, Auth will fetch and cache the metadata auto
 
 ```sh
 curl -X POST 'http://<your-domain>/auth/v1/admin/sso/providers' \
-  -H 'Authorization: Bearer your-service-role-key' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-service-role-key' \
+  -H 'apikey: your-supabase-secret-key' \
   -d '{
     "type": "saml",
     "metadata_url": "https://idp.example.com/saml/metadata",
@@ -190,9 +189,8 @@ If you have the IdP metadata as an XML string:
 
 ```sh
 curl -X POST 'http://<your-domain>/auth/v1/admin/sso/providers' \
-  -H 'Authorization: Bearer your-service-role-key' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-service-role-key' \
+  -H 'apikey: your-supabase-secret-key' \
   -d '{
     "type": "saml",
     "metadata_xml": "<EntityDescriptor ...>...</EntityDescriptor>",
@@ -384,41 +382,36 @@ Mapped attributes are stored in the user's `raw_user_meta_data` and are availabl
 
 ```sh
 curl 'http://<your-domain>/auth/v1/admin/sso/providers' \
-  -H 'Authorization: Bearer your-service-role-key' \
-  -H 'apikey: your-service-role-key'
+  -H 'apikey: your-supabase-secret-key'
 ```
 
 Filter by resource ID using exact match:
 
 ```sh
 curl 'http://<your-domain>/auth/v1/admin/sso/providers?resource_id=my-idp' \
-  -H 'Authorization: Bearer your-service-role-key' \
-  -H 'apikey: your-service-role-key'
+  -H 'apikey: your-supabase-secret-key'
 ```
 
 or prefix match:
 
 ```sh
 curl 'http://<your-domain>/auth/v1/admin/sso/providers?resource_id_prefix=prod-' \
-  -H 'Authorization: Bearer your-service-role-key' \
-  -H 'apikey: your-service-role-key'
+  -H 'apikey: your-supabase-secret-key'
 ```
 
 ### Get a specific provider
 
 ```sh
 curl 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
-  -H 'Authorization: Bearer your-service-role-key' \
-  -H 'apikey: your-service-role-key'
+  -H 'apikey: your-supabase-secret-key'
 ```
 
 ### Update a provider
 
 ```sh
 curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
-  -H 'Authorization: Bearer your-service-role-key' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-service-role-key' \
+  -H 'apikey: your-supabase-secret-key' \
   -d '{
     "domains": ["example.com", "subsidiary.com"],
     "attribute_mapping": {
@@ -435,9 +428,8 @@ curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
 
 ```sh
 curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
-  -H 'Authorization: Bearer your-service-role-key' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-service-role-key' \
+  -H 'apikey: your-supabase-secret-key' \
   -d '{ "disabled": true }'
 ```
 
@@ -445,8 +437,7 @@ curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
 
 ```sh
 curl -X DELETE 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
-  -H 'Authorization: Bearer your-service-role-key' \
-  -H 'apikey: your-service-role-key'
+  -H 'apikey: your-supabase-secret-key'
 ```
 
 ## Client-side integration
@@ -456,7 +447,7 @@ curl -X DELETE 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}'
 ```js
 import { createClient } from '@supabase/supabase-js'
 
-const supabase = createClient('http://<your-domain>', 'your-anon-key')
+const supabase = createClient('http://<your-domain>', 'your-supabase-publishable-key')
 
 // Option 1: SSO by email domain
 const { data, error } = await supabase.auth.signInWithSSO({
@@ -483,7 +474,7 @@ By domain:
 ```sh
 curl -X POST 'http://<your-domain>/auth/v1/sso' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-anon-key' \
+  -H 'apikey: your-supabase-publishable-key' \
   -d '{
     "domain": "example.com",
     "skip_http_redirect": true
@@ -495,7 +486,7 @@ By provider ID:
 ```sh
 curl -X POST 'http://<your-domain>/auth/v1/sso' \
   -H 'Content-Type: application/json' \
-  -H 'apikey: your-anon-key' \
+  -H 'apikey: your-supabase-publishable-key' \
   -d '{
     "provider_id": "d3f5a1b2-...",
     "skip_http_redirect": true
@@ -523,7 +514,7 @@ To verify the session was created:
 ```sh
 curl 'http://<your-domain>/auth/v1/user' \
   -H 'Authorization: Bearer user-session-token' \
-  -H 'apikey: your-anon-key'
+  -H 'apikey: your-supabase-publishable-key'
 ```
 
 The response should include `app_metadata.provider: "sso:saml"` and any mapped attributes in `user_metadata`.

From bd43802d7b4daa777d55f3b9b01e9062c7988dc0 Mon Sep 17 00:00:00 2001
From: "Andrey A." <56412611+aantti@users.noreply.github.com>
Date: Fri, 4 Sep 2026 21:35:49 +0200
Subject: [PATCH 2/2] docs(self-hosted): add a section about key rotation to
 docker guide (#50015)

---
 .../content/guides/self-hosting/docker.mdx     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/apps/docs/content/guides/self-hosting/docker.mdx b/apps/docs/content/guides/self-hosting/docker.mdx
index ca849c63247ea..0573d84fed6dd 100644
--- a/apps/docs/content/guides/self-hosting/docker.mdx
+++ b/apps/docs/content/guides/self-hosting/docker.mdx
@@ -492,6 +492,24 @@ The script generates a new password, updates all database roles, and modifies yo
 sh run.sh recreate
 ```
 
+### Rotating API keys
+
+Unlike the managed platform, where you rotate keys from the Dashboard, self-hosted API keys live in your `.env` file. To rotate the publishable and secret keys (`SUPABASE_PUBLISHABLE_KEY` and `SUPABASE_SECRET_KEY`) without changing the asymmetric signing key pair, run:
+
+```sh
+sh utils/rotate-new-api-keys.sh --update-env
+```
+
+Then restart the services and update your applications with the new keys:
+
+```sh
+sh run.sh recreate
+```
+
+Use the publishable key in client apps and the secret key only in trusted server-side environments. Rotating these keys does not invalidate existing user session tokens. You can also set a custom value by editing `SUPABASE_PUBLISHABLE_KEY` or `SUPABASE_SECRET_KEY` in `.env` directly, then recreating the services.
+
+For rotating versus fully regenerating the asymmetric key pair (which does affect active sessions), see [New API Keys and Asymmetric Authentication](/docs/guides/self-hosting/self-hosted-auth-keys#regenerating-asymmetric-key-pair).
+
 ### Configuring secrets
 
 The `generate-keys.sh` script sets the following secrets automatically. You can also configure them manually in the `.env` file if needed: