## Client-Server API
Breaking Changes
- Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method as per [MSC2630](https://github.com/matrix-org/matrix-doc/pull/2630). ([#2687](https://github.com/matrix-org/matrix-doc/issues/2687))
- Add `m.key.verification.ready` and `m.key.verification.done` to key verification framework as per [MSC2366](https://github.com/matrix-org/matrix-doc/pull/2366). ([#3139](https://github.com/matrix-org/matrix-doc/issues/3139))
Deprecations
- Deprecate starting verifications that don't start with `m.key.verification.request` as per [MSC3122](https://github.com/matrix-org/matrix-doc/pull/3122). ([#3199](https://github.com/matrix-org/matrix-doc/issues/3199))
New Endpoints
- Add key backup (`/room_keys/*`) endpoints as per [MSC1219](https://github.com/matrix-org/matrix-doc/pull/1219). ([#2387](https://github.com/matrix-org/matrix-doc/issues/2387), [#2639](https://github.com/matrix-org/matrix-doc/issues/2639))
- Add `POST /keys/device_signing/upload` and `POST /keys/signatures/upload` as per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756). ([#2536](https://github.com/matrix-org/matrix-doc/issues/2536))
- Add `/knock` endpoint as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). ([#3154](https://github.com/matrix-org/matrix-doc/issues/3154))
- Add `/login/sso/redirect/{idpId}` as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858). ([#3163](https://github.com/matrix-org/matrix-doc/issues/3163))
Removed Endpoints
- Remove unimplemented `m.login.oauth2` and `m.login.token` user-interactive authentication mechanisms as per [MSC2610](https://github.com/matrix-org/matrix-doc/pull/2610) and [MSC2611](https://github.com/matrix-org/matrix-doc/pull/2611). ([#2609](https://github.com/matrix-org/matrix-doc/issues/2609))
Backwards Compatible Changes
- Document how clients can advise recipients that it is withholding decryption keys as per [MSC2399](https://github.com/matrix-org/matrix-doc/pull/2399). ([#2399](https://github.com/matrix-org/matrix-doc/issues/2399))
- Add cross-signing properties to the response of `POST /keys/query` as per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756). ([#2536](https://github.com/matrix-org/matrix-doc/issues/2536))
- Document Secure Secret Storage and Sharing as per [MSC1946](https://github.com/matrix-org/matrix-doc/pull/1946) and [MSC2472](https://github.com/matrix-org/matrix-doc/pull/2472). ([#2597](https://github.com/matrix-org/matrix-doc/issues/2597))
- Add a `device_id` parameter to login fallback as per [MSC2604](https://github.com/matrix-org/matrix-doc/pull/2604). ([#2709](https://github.com/matrix-org/matrix-doc/issues/2709))
- Added a common set of translations for SAS Emoji. ([#2728](https://github.com/matrix-org/matrix-doc/issues/2728))
- Added support for `reason` on all membership events and related endpoints as per [MSC2367](https://github.com/matrix-org/matrix-doc/pull/2367). ([#2795](https://github.com/matrix-org/matrix-doc/issues/2795))
- Add a 404 `M_NOT_FOUND` error to push rule endpoints as per [MSC2663](https://github.com/matrix-org/matrix-doc/pull/2663). ([#2796](https://github.com/matrix-org/matrix-doc/issues/2796))
- Make `reason` and `score` parameters optional in the content reporting API as per [MSC2414](https://github.com/matrix-org/matrix-doc/pull/2414). ([#2807](https://github.com/matrix-org/matrix-doc/issues/2807))
- Allow guests to get the list of members for a room as per [MSC2689](https://github.com/matrix-org/matrix-doc/pull/2689). ([#2808](https://github.com/matrix-org/matrix-doc/issues/2808))
- Add support for spoilers as per [MSC2010](https://github.com/matrix-org/matrix-doc/pull/2010) and [MSC2557](https://github.com/matrix-org/matrix-doc/pull/2557), and `color` attribute as per [MSC2422](https://github.com/matrix-org/matrix-doc/pull/2422). ([#3098](https://github.com/matrix-org/matrix-doc/issues/3098))
- Add `` and `` to the suggested HTML subset as per [MSC2184](https://github.com/matrix-org/matrix-doc/pull/2184). ([#3100](https://github.com/matrix-org/matrix-doc/issues/3100))
- Add key verification using in-room messages as per [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241). ([#3139](https://github.com/matrix-org/matrix-doc/issues/3139), [#3150](https://github.com/matrix-org/matrix-doc/issues/3150))
- Add information about using SSSS for cross-signing and key backup. ([#3147](https://github.com/matrix-org/matrix-doc/issues/3147))
- Add key verification method using QR codes as per [MSC1544](https://github.com/matrix-org/matrix-doc/pull/1544). ([#3149](https://github.com/matrix-org/matrix-doc/issues/3149))
- Document how clients can simplify usage of Secure Secret Storage as per [MSC2874](https://github.com/matrix-org/matrix-doc/pull/2874). ([#3151](https://github.com/matrix-org/matrix-doc/issues/3151))
- Add support for knocking, as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). ([#3154](https://github.com/matrix-org/matrix-doc/issues/3154), [#3254](https://github.com/matrix-org/matrix-doc/issues/3254))
- Multiple SSO providers are possible through `m.login.sso` as per [MSC2858](https://github.com/matrix-org/matrix-doc/pull/2858). ([#3163](https://github.com/matrix-org/matrix-doc/issues/3163))
- Add `device_id` to `/account/whoami` response as per [MSC2033](https://github.com/matrix-org/matrix-doc/pull/2033). ([#3166](https://github.com/matrix-org/matrix-doc/issues/3166))
- Downgrade identity server discovery failures to `FAIL_PROMPT` as per [MSC2284](https://github.com/matrix-org/matrix-doc/pull/2284). ([#3169](https://github.com/matrix-org/matrix-doc/issues/3169))
- Re-version all endpoints to be `v3` as a starting point instead of `r0` as per [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844). ([#3421](https://github.com/matrix-org/matrix-doc/issues/3421))
Spec Clarifications
- Fix issues with `age` and `unsigned` being shown in the wrong places. ([#2591](https://github.com/matrix-org/matrix-doc/issues/2591))
- Fix definitions for room version capabilities. ([#2592](https://github.com/matrix-org/matrix-doc/issues/2592))
- Fix various typos throughout the specification. ([#2594](https://github.com/matrix-org/matrix-doc/issues/2594), [#2599](https://github.com/matrix-org/matrix-doc/issues/2599), [#2809](https://github.com/matrix-org/matrix-doc/issues/2809), [#2878](https://github.com/matrix-org/matrix-doc/issues/2878), [#2885](https://github.com/matrix-org/matrix-doc/issues/2885), [#2888](https://github.com/matrix-org/matrix-doc/issues/2888), [#3116](https://github.com/matrix-org/matrix-doc/issues/3116), [#3339](https://github.com/matrix-org/matrix-doc/issues/3339))
- Clarify link to OpenID Connect specification. ([#2605](https://github.com/matrix-org/matrix-doc/issues/2605))
- Clarify the behaviour of SSO login and UI-Auth. ([#2608](https://github.com/matrix-org/matrix-doc/issues/2608))
- Remove spurious `room_id` from `/sync` examples. ([#2629](https://github.com/matrix-org/matrix-doc/issues/2629))
- Reorganize information in Push Notifications module for clarity. ([#2634](https://github.com/matrix-org/matrix-doc/issues/2634))
- Improve consistency and clarity of event schema `title`s. ([#2647](https://github.com/matrix-org/matrix-doc/issues/2647))
- Fix schema issues in `m.key.verification.accept` and secret storage. ([#2653](https://github.com/matrix-org/matrix-doc/issues/2653))
- Reword "UI Authorization" to "User-Interactive Authentication" to be more clear. ([#2667](https://github.com/matrix-org/matrix-doc/issues/2667))
- Fix schemas for push rule actions to represent their alternative object form. ([#2669](https://github.com/matrix-org/matrix-doc/issues/2669))
- Fix usage of `highlight` tweak for consistency. ([#2670](https://github.com/matrix-org/matrix-doc/issues/2670))
- Clarify the behaviour of `state` for `/sync` with lazy-loading. ([#2754](https://github.com/matrix-org/matrix-doc/issues/2754))
- Clarify description of `m.room.redaction` event. ([#2814](https://github.com/matrix-org/matrix-doc/issues/2814))
- Mark `messages` as a required JSON body field in `PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId}` calls. ([#2928](https://github.com/matrix-org/matrix-doc/issues/2928))
- Correct examples of `client_secret` request body parameters so that they do not include invalid characters. ([#2985](https://github.com/matrix-org/matrix-doc/issues/2985))
- Fix example MXC URI for `m.presence`. ([#3091](https://github.com/matrix-org/matrix-doc/issues/3091))
- Clarify that event bodies are untrusted, as per [MSC2801](https://github.com/matrix-org/matrix-doc/pull/2801). ([#3099](https://github.com/matrix-org/matrix-doc/issues/3099))
- Fix the maximum event size restriction (65535 bytes -> 65536). ([#3127](https://github.com/matrix-org/matrix-doc/issues/3127))
- Update `Access-Control-Allow-Headers` recommendation to fit CORS specification. ([#3225](https://github.com/matrix-org/matrix-doc/issues/3225))
- Explicitly state that `replacement_room` is a room ID in `m.room.tombstone` events. ([#3233](https://github.com/matrix-org/matrix-doc/issues/3233))
- Clarify that all request bodies are required. ([#3238](https://github.com/matrix-org/matrix-doc/issues/3238), [#3332](https://github.com/matrix-org/matrix-doc/issues/3332))
- Add missing titles to some scheams. ([#3330](https://github.com/matrix-org/matrix-doc/issues/3330))
- Add User-Interactive Authentication fields to cross-signing APIs as per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756). ([#3331](https://github.com/matrix-org/matrix-doc/issues/3331))
- Mention that a canonical alias event should be added when a room is created with an alias. ([#3337](https://github.com/matrix-org/matrix-doc/issues/3337))
- Add an 'API conventions' section to the Appendices. ([#3350](https://github.com/matrix-org/matrix-doc/issues/3350))
- Clarify the documentation around the pagination tokens used by `/sync`, `/rooms/{room_id}/messages`, `/initialSync`, `/rooms/{room_id}/initialSync`, and `/notifications`. ([#3353](https://github.com/matrix-org/matrix-doc/issues/3353))
- Remove the inaccurate 'Pagination' section. ([#3366](https://github.com/matrix-org/matrix-doc/issues/3366))
- Clarify how `redacted_because` is meant to work. ([#3411](https://github.com/matrix-org/matrix-doc/issues/3411))
- Remove extraneous `mimetype` from `EncryptedFile` examples, as per [MSC2582](https://github.com/matrix-org/matrix-doc/pull/2582). ([#3412](https://github.com/matrix-org/matrix-doc/issues/3412))
- Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3420](https://github.com/matrix-org/matrix-doc/issues/3420))
- Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471))
## Server-Server API
New Endpoints
- Add `/make_knock` and `/send_knock` endpoints as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). ([#3154](https://github.com/matrix-org/matrix-doc/issues/3154))
Backwards Compatible Changes
- Add cross-signing information to `GET /user/keys` and `GET /user/devices/{userId}`, `m.device_list_update` EDU, and a new `m.signing_key_update` EDU as per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756). ([#2536](https://github.com/matrix-org/matrix-doc/issues/2536))
- Add support for knocking, as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403). ([#3154](https://github.com/matrix-org/matrix-doc/issues/3154))
Spec Clarifications
- Specify that `GET /_matrix/federation/v1/make_join/{roomId}/{userId}` can return a 404 if the room is unknown. ([#2688](https://github.com/matrix-org/matrix-doc/issues/2688))
- Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888), [#3116](https://github.com/matrix-org/matrix-doc/issues/3116), [#3128](https://github.com/matrix-org/matrix-doc/issues/3128), [#3207](https://github.com/matrix-org/matrix-doc/issues/3207))
- Correct the `/_matrix/federation/v1/user/devices/{userId}` response which actually returns `"self_signing_key"` instead of `"self_signing_keys"`. ([#3312](https://github.com/matrix-org/matrix-doc/issues/3312))
- Explain the reasons why `` TLS certificate is needed rather than `` for SRV delegation. ([#3322](https://github.com/matrix-org/matrix-doc/issues/3322))
- Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340))
## Application Service API
Spec Clarifications
- Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888))
## Identity Service API
New Endpoints
- Add `GET /_matrix/identity/versions` API as per [MSC2320](https://github.com/matrix-org/matrix-doc/pull/2320). ([#3101](https://github.com/matrix-org/matrix-doc/issues/3101))
Removed Endpoints
- The v1 identity service API has been removed in favour of the v2 API, as per [MSC2713](https://github.com/matrix-org/matrix-doc/pull/2713). ([#3170](https://github.com/matrix-org/matrix-doc/issues/3170))
Spec Clarifications
- Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888))
- Clarify that some identifiers must be case folded prior to processing, as per [MSC2265](https://github.com/matrix-org/matrix-doc/pull/2265). ([#3167](https://github.com/matrix-org/matrix-doc/issues/3167), [#3176](https://github.com/matrix-org/matrix-doc/issues/3176))
- Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459))
## Push Gateway API
Spec Clarifications
- Clarify where to get information about the various parameter values for the notify endpoint. ([#2763](https://github.com/matrix-org/matrix-doc/issues/2763))