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] 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 ca849c63247..0573d84fed6 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: