diff --git a/changelog.d/18138.doc b/changelog.d/18138.doc
new file mode 100644
index 0000000000000000000000000000000000000000..5f07cd27634aac61f0f70c2006e34eefd6dd48e8
--- /dev/null
+++ b/changelog.d/18138.doc
@@ -0,0 +1 @@
+Document consequences of replacing secrets.
\ No newline at end of file
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 92ab6438c1d267c1ac8f72352ec9aac8de3d37d3..e3c06d5371921ad348fe725e57197259c260fe6c 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -2592,6 +2592,14 @@ This is primarily intended for use with the `register_new_matrix_user` script
 (see [Registering a user](../../setup/installation.md#registering-a-user));
 however, the interface is [documented](../../admin_api/register_api.html).
 
+Replacing an existing `registration_shared_secret` with a new one requires users
+of the [Shared-Secret Registration API](../../admin_api/register_api.html) to
+start using the new secret for requesting any further one-time nonces.
+
+> ⚠️ **Warning** – The additional consequences of replacing
+> [`macaroon_secret_key`](#macaroon_secret_key) will apply in case it delegates
+> to `registration_shared_secret`.
+
 See also [`registration_shared_secret_path`](#registration_shared_secret_path).
 
 Example configuration:
@@ -3168,6 +3176,11 @@ A secret which is used to sign
 If none is specified, the `registration_shared_secret` is used, if one is given;
 otherwise, a secret key is derived from the signing key.
 
+> ⚠️ **Warning** – Replacing an existing `macaroon_secret_key` with a new one
+> will lead to invalidation of access tokens for all guest users. It will also
+> break unsubscribe links in emails sent before the change. An unlucky user
+> might encounter a broken SSO login flow and would have to start again.
+
 Example configuration:
 ```yaml
 macaroon_secret_key: <PRIVATE STRING>
@@ -3195,6 +3208,9 @@ A secret which is used to calculate HMACs for form values, to stop
 falsification of values. Must be specified for the User Consent
 forms to work.
 
+Replacing an existing `form_secret` with a new one might break the user consent
+page for an unlucky user and require them to reopen the page from a new link.
+
 Example configuration:
 ```yaml
 form_secret: <PRIVATE STRING>
@@ -4443,6 +4459,9 @@ HTTP requests from workers.
 The default, this value is omitted (equivalently `null`), which means that
 traffic between the workers and the main process is not authenticated.
 
+Replacing an existing `worker_replication_secret` with a new one will break
+communication with all workers that have not yet updated their secret.
+
 Example configuration:
 ```yaml
 worker_replication_secret: "secret_secret"