Clarify that refreshed access tokens don't invalidate the scope of txnid (#1236)

changelogs/client_server/newsfragments/1236.clarification

@@ -0,0 +1 @@
+Reinforce the relationship of refreshed access tokens to transaction IDs.

content/client-server-api/_index.md

@@ -213,12 +213,19 @@ See the [Server Notices](#server-notices) module for more information.
 
 The client-server API typically uses `HTTP PUT` to submit requests with
 a client-generated transaction identifier. This means that these
-requests are idempotent. The scope of a transaction identifier is a
+requests are idempotent. It **only** serves to identify new requests
-particular access token. It **only** serves to identify new requests
 from retransmits. After the request has finished, the `{txnId}` value
 should be changed (how is not specified; a monotonically increasing
 integer is recommended).
 
+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.
+
 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.

data/api/client-server/definitions/client_event_without_room_id.yaml

@@ -94,7 +94,7 @@ properties:
         }
       transaction_id:
         description: |
-          The client-supplied transaction ID, for example, provided via
+          The client-supplied [transaction ID](/client-server-api/#transaction-identifiers), for example, provided via
           `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,
           if the client being given the event is the same one which sent it.
         type: string

data/api/client-server/redaction.yaml

@@ -62,7 +62,7 @@ paths:
           name: txnId
           type: string
           description: |-
-            The transaction ID for this event. Clients should generate a
+            The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a
             unique ID; it will be used by the server to ensure idempotency of requests.
           required: true
           x-example: "37"

data/api/client-server/room_send.yaml

@@ -58,7 +58,7 @@ paths:
           name: txnId
           type: string
           description: |-
-            The transaction ID for this event. Clients should generate an
+            The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
             ID unique across requests with the same access token; it will be
             used by the server to ensure idempotency of requests.
           required: true

data/api/client-server/to_device.yaml

@@ -48,7 +48,7 @@ paths:
           name: txnId
           type: string
           description: |-
-            The transaction ID for this event. Clients should generate an
+            The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
             ID unique across requests with the same access token; it will be
             used by the server to ensure idempotency of requests.
           required: true