From 6dc7b95e18e1d09ada233c44463b77ea0364fad6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 4 Aug 2022 13:33:16 -0400
Subject: [PATCH] Use auth header instead of query param for hs->as comms
 (#1200)

* Use auth header instead of query param for hs->as comms

MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/2832

* Fix for OpenAPI 2
---
 .../newsfragments/1200.breaking               |  1 +
 content/application-service-api.md            | 26 +++++++++++++++----
 .../definitions/security.yaml                 |  7 ++---
 3 files changed, 26 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/application_service/newsfragments/1200.breaking

diff --git a/changelogs/application_service/newsfragments/1200.breaking b/changelogs/application_service/newsfragments/1200.breaking
new file mode 100644
index 00000000..8b362072
--- /dev/null
+++ b/changelogs/application_service/newsfragments/1200.breaking
@@ -0,0 +1 @@
+Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832).
\ No newline at end of file
diff --git a/content/application-service-api.md b/content/application-service-api.md
index 61227660..029e0350 100644
--- a/content/application-service-api.md
+++ b/content/application-service-api.md
@@ -127,11 +127,27 @@ this.
 
 #### Authorization
 
-Homeservers MUST include a query parameter named `access_token`
-containing the `hs_token` from the application service's registration
-when making requests to the application service. Application services
-MUST verify the provided `access_token` matches their known `hs_token`,
-failing the request with an `M_FORBIDDEN` error if it does not match.
+{{% changed-in v="1.4" %}}
+
+Homeservers MUST include an `Authorization` header, containing the `hs_token`
+from the application service's registration, when making requests to the
+application service. Application services MUST verify that the provided
+`Bearer` token matches their known `hs_token`, failing the request with
+an `M_FORBIDDEN` error if it does not match.
+
+The format of the `Authorization` header is similar to the [Client-Server API](/client-server-api/#client-authentication):
+`Bearer TheHSTokenGoesHere`.
+
+{{% boxes/note %}}
+In previous versions of this specification, an `access_token` query
+parameter was used instead. Servers should only send this query parameter
+if supporting legacy versions of the specification.
+
+If sending the `query_string`, it is encouraged to send it alongside
+the `Authorization` header for maximum compatibility.
+
+Application services should ensure both match if both are provided.
+{{% /boxes/note %}}
 
 #### Legacy routes
 
diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml
index 6d7edd3a..b28d033a 100644
--- a/data/api/application-service/definitions/security.yaml
+++ b/data/api/application-service/definitions/security.yaml
@@ -1,4 +1,5 @@
 # Copyright 2018 New Vector Ltd
+# Copyright 2022 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,6 +14,6 @@
 # limitations under the License.
 homeserverAccessToken:
   type: apiKey
-  description: The `hs_token` provided by the application service's registration.
-  name: access_token
-  in: query
+  name: Authorization
+  in: header
+  description: The `Bearer` `hs_token` provided by the application service's registration.