From c1ac9a9ad793c07c1699b5b0fd2ea01436513443 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 16 May 2023 21:33:05 +0100
Subject: [PATCH] Update transaction ID scope (#1526)

---
 .../client_server/newsfragments/1526.feature  |  1 +
 content/client-server-api/_index.md           | 30 +++++++++++++------
 2 files changed, 22 insertions(+), 9 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1526.feature

diff --git a/changelogs/client_server/newsfragments/1526.feature b/changelogs/client_server/newsfragments/1526.feature
new file mode 100644
index 00000000..f26f96eb
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1526.feature
@@ -0,0 +1 @@
+Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index cf00870b..798835a0 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -237,19 +237,32 @@ For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
 would return a `200 OK` with the `event_id` of the original request in
 the response body.
 
-As well as the HTTP path, the scope of a transaction ID is a "client
-session", where that session is identified by a particular access token.
-When [refreshing](#refreshing-access-tokens) an access token, the
-transaction ID's scope is retained. This means that if a client with
-token `A` uses `TXN1` as their transaction ID, refreshes the token to
-`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
-and ignored. If the client logs out and back in between the `A` and `B`
-tokens, `TXN1` could be used once for each.
+The scope of a transaction ID is for a single [device](../index.html#devices),
+and a single HTTP endpoint. In other words: a single device could use the same
+transaction ID for a request to [`PUT
+/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
+and [`PUT
+/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid),
+and the two requests would be considered distinct because the two are
+considered separate endpoints. Similarly, if a client logs out and back in
+between two requests using the same transaction ID, the requests are distinct
+because the act of logging in and out creates a new device (unless an existing
+`device_id` is passed to [`POST
+/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a
+client re-uses a transaction ID for the same endpoint after
+[refreshing](#refreshing-access-tokens) an access token, it will be assumed to
+be a duplicate request and ignored. See also
+[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices).
 
 Some API endpoints may allow or require the use of `POST` requests
 without a transaction ID. Where this is optional, the use of a `PUT`
 request is strongly recommended.
 
+{{% boxes/rationale %}}
+Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than
+devices.
+{{% /boxes/rationale %}}
+
 ## Web Browser Clients
 
 It is realistic to expect that some clients will be written to be run
@@ -2671,4 +2684,3 @@ systems.
 {{< cs-module name="event_annotations" >}}
 {{< cs-module name="threading" >}}
 {{< cs-module name="reference_relations" >}}
-