From 006ca6a95a565741ce0b774b85fc6e39896a567c Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Mon, 26 Dec 2022 10:31:22 +0000
Subject: [PATCH] remove keyId from /keys endpoints (#3938)

---
 .../3938-remove-keyid-from-keys-endpoints.md  | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 proposals/3938-remove-keyid-from-keys-endpoints.md

diff --git a/proposals/3938-remove-keyid-from-keys-endpoints.md b/proposals/3938-remove-keyid-from-keys-endpoints.md
new file mode 100644
index 00000000..000df70d
--- /dev/null
+++ b/proposals/3938-remove-keyid-from-keys-endpoints.md
@@ -0,0 +1,31 @@
+# MSC3938: Remove deprecated `keyId` parameters from `/keys` endpoints
+
+The `keyId` path parameter on
+[`GET /_matrix/key/v2/server/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2serverkeyid)
+and [`GET /_matrix/key/v2/query/{serverName}/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2queryservernamekeyid)
+has been deprecated since before the Matrix spec was formally versioned
+([pull request](https://github.com/matrix-org/matrix-spec-proposals/pull/1423)).
+
+The reason for deprecation was primarily that it was never implemented
+correctly: making a request with a `keyId` had the same effect as making a
+request without one.
+
+## Proposal
+
+The deprecated `keyId` path parameter should be removed from
+[`GET /_matrix/key/v2/server/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2serverkeyid)
+and [`GET /_matrix/key/v2/query/{serverName}/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2queryservernamekeyid).
+
+Furthermore, a trailing slash at the end of the endpoint path will no longer be permitted.
+
+The new endpoints will simply be `GET /_matrix/key/v2/server` and `GET
+/_matrix/key/v2/query/{serverName}` respectively, and they will return all
+available keys for the given server.
+
+## Potential issues
+
+This is a breaking change: some servers (such as Synapse, until [very
+recently](https://github.com/matrix-org/synapse/pull/14525)) may include the
+`{keyId}` in outgoing requests.
+
+