From 83da144a7be0c7243b4b2c65c5645f52c62203f0 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 3 Oct 2025 15:02:26 -0600
Subject: [PATCH] Spec device ID masquerading

---
 .../application_service/newsfragments/2221.feature  |  1 +
 changelogs/client_server/newsfragments/2221.feature |  1 +
 content/application-service-api.md                  | 13 ++++++++++++-
 content/client-server-api/_index.md                 |  4 ++++
 4 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/application_service/newsfragments/2221.feature
 create mode 100644 changelogs/client_server/newsfragments/2221.feature

diff --git a/changelogs/application_service/newsfragments/2221.feature b/changelogs/application_service/newsfragments/2221.feature
new file mode 100644
index 00000000..400d98ef
--- /dev/null
+++ b/changelogs/application_service/newsfragments/2221.feature
@@ -0,0 +1 @@
+Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/2221.feature b/changelogs/client_server/newsfragments/2221.feature
new file mode 100644
index 00000000..400d98ef
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2221.feature
@@ -0,0 +1 @@
+Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
\ No newline at end of file
diff --git a/content/application-service-api.md b/content/application-service-api.md
index 46c3efca..cd0ae508 100644
--- a/content/application-service-api.md
+++ b/content/application-service-api.md
@@ -356,6 +356,7 @@ service would like to masquerade as.
 Inputs:
 -   Application service token (`as_token`)
 -   User ID in the AS namespace to act as.
+-   Device ID belonging to the User ID to act with.
 
 Notes:
 -   This applies to all aspects of the Client-Server API, except for
@@ -375,9 +376,19 @@ service's `user` namespaces. If the parameter is missing, the homeserver
 is to assume the application service intends to act as the user implied
 by the `sender_localpart` property of the registration.
 
+{{% added-in v="1.17" %}} Application services MAY similarly masquerade
+as a specific device ID belonging the user ID through use of the `device_id`
+query string parameter on the request. If the given device ID is not known
+to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
+If no `user_id` is supplied, the `device_id` MUST belong to the user implied
+by the `sender_localpart` property of the application service's registration.
+If no `device_id` is supplied, the homeserver is to assume the request is
+being made without a device ID and will fail to complete operations which
+require a device ID (such as uploading one-time keys).
+
 An example request would be:
 
-    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
+    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
     Authorization: Bearer YourApplicationServiceTokenHere
 
 #### Timestamp massaging
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 69757086..f7cfcd56 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -132,6 +132,10 @@ The server did not understand the request. This is expected to be returned with
 a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
 code if the endpoint is implemented, but the incorrect HTTP method is used.
 
+`M_UNKNOWN_DEVICE`
+{{% added-in v="1.17" %}} The device ID supplied by the application service does
+not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+
 `M_UNKNOWN`
 An unknown error has occurred.