diff --git a/changelogs/client_server/newsfragments/1236.clarification b/changelogs/client_server/newsfragments/1236.clarification new file mode 100644 index 00000000..36052275 --- /dev/null +++ b/changelogs/client_server/newsfragments/1236.clarification @@ -0,0 +1 @@ +Reinforce the relationship of refreshed access tokens to transaction IDs. \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b1b55159..b29aeb32 100644 --- a/content/client-server-api/_index.md +++ b/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 -particular access token. It **only** serves to identify new requests +requests are idempotent. 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. diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml index c4db8b0e..0decb6f3 100644 --- a/data/api/client-server/definitions/client_event_without_room_id.yaml +++ b/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 diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml index 37ff9741..8fa9cbef 100644 --- a/data/api/client-server/redaction.yaml +++ b/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" diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml index 28591a3a..e38d2ebd 100644 --- a/data/api/client-server/room_send.yaml +++ b/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 diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml index fb0c1d37..266593e1 100644 --- a/data/api/client-server/to_device.yaml +++ b/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