From 48051c3450f794f31c0bc1a90fbe29d1d714e95c Mon Sep 17 00:00:00 2001
From: Andy Balaam <andy.balaam@matrix.org>
Date: Wed, 22 Apr 2026 10:27:55 +0100
Subject: [PATCH] Specify m.key_backup account data (MSC4287) (#2354)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>
Co-authored-by: Tulir Asokan <tulir@maunium.net>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
---
 .../client_server/newsfragments/2354.feature  |  1 +
 .../modules/end_to_end_encryption.md          | 37 +++++++++++++++++++
 data/event-schemas/examples/m.key_backup.yaml |  7 ++++
 data/event-schemas/schema/m.key_backup.yaml   | 24 ++++++++++++
 4 files changed, 69 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/2354.feature
 create mode 100644 data/event-schemas/examples/m.key_backup.yaml
 create mode 100644 data/event-schemas/schema/m.key_backup.yaml

diff --git a/changelogs/client_server/newsfragments/2354.feature b/changelogs/client_server/newsfragments/2354.feature
new file mode 100644
index 00000000..7508cc95
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2354.feature
@@ -0,0 +1 @@
+Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index 1c3a82da..75acd93b 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -1479,6 +1479,43 @@ potential new key backup algorithm version that would fix this issue.
 
 {{% http-api spec="client-server" api="key_backup" %}}
 
+###### Key backup enabled preference
+
+{{% added-in v="1.19" %}}
+
+This enables clients to track a user's preference about enabling or
+disabling [server-side backups of room keys](#server-side-key-backups). The data
+is stored in the [`m.key_backup`](#mkey_backup) global
+[account data](#client-config).
+
+{{% event event="m.key_backup" %}}
+
+When a user signs in to a client which supports encryption and key backup:
+
+* If this event type exists in account data and contains the specified property
+  in the correct format, clients which support key backup MUST take account of
+  its contents in their behaviour. For example, clients may automatically turn
+  on/off key backup based on the property, or prompt the user, using the
+  property value as a default. (Because this property is server-controlled,
+  clients may wish to confirm the user's intention.)
+
+* If this event type does not exist in account data, or if it does not contain
+  the `enabled` property, or if the value of `enabled` is not a boolean value,
+  clients MUST ignore the existing value and MAY decide whether or not to
+  perform key backup, possibly based on user input.
+
+If the user turns on key backups, clients MUST set this event type in account
+data, to `"enabled": true`.
+
+If the user turns off key backups, clients MUST set this event type in account
+data, to `"enabled": false`.
+
+Clients are not required to monitor the `m.key_backup` account data actively.
+Clients MAY monitor the setting but should be aware that changing this setting
+without user interaction based on choices made in a different client (or a
+compromised homeserver) may cause unforeseen security problems or simply be
+unexpected by users.
+
 ##### Key exports
 
 Keys can be manually exported from one device to an encrypted file,
diff --git a/data/event-schemas/examples/m.key_backup.yaml b/data/event-schemas/examples/m.key_backup.yaml
new file mode 100644
index 00000000..678c0ba9
--- /dev/null
+++ b/data/event-schemas/examples/m.key_backup.yaml
@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.key_backup",
+  "content": {
+    "enabled": false
+  }
+}
diff --git a/data/event-schemas/schema/m.key_backup.yaml b/data/event-schemas/schema/m.key_backup.yaml
new file mode 100644
index 00000000..5b422203
--- /dev/null
+++ b/data/event-schemas/schema/m.key_backup.yaml
@@ -0,0 +1,24 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Allows clients to track user preferences about key backup.
+properties:
+  content:
+    type: object
+    properties:
+      enabled:
+        type: boolean
+        description: |-
+          True if the user chose to enable key backup. False if the user chose
+          to disable key backup.
+    required:
+      - enabled
+  type:
+    type: string
+    enum:
+      - m.key_backup
+title: Key Backup Event
+type: object