Encourage appservices to use the Authorization header

specification/application_service_api.rst

@@ -185,29 +185,34 @@ homeserver.
 Identity assertion
 ++++++++++++++++++
 The client-server API infers the user ID from the ``access_token`` provided in
-every request. It would be an annoying amount of book-keeping to maintain tokens
-for every virtual user. It would be preferable if the application service could
-use the CS API with its own ``as_token`` instead, and specify the virtual user
-they wish to be acting on behalf of. For real users, this would require
-additional permissions granting the AS permission to masquerade as a matrix user.
+every request. To avoid the application service from having to keep track of each
+user's access token, the application service should identify itself to the Client-Server
+API by providing its ``as_token`` instead for the ``access_token`` alongside the
+user the application service would like to masquerade as.
 
 Inputs:
- - Application service token (``access_token``)
+ - Application service token (``as_token``)
  - User ID in the AS namespace to act as.
 
 Notes:
- - This will apply on all aspects of the CS API, except for Account Management.
+ - This applies to all aspects of the Client-Server API, except for Account Management.
  - The ``as_token`` is inserted into ``access_token`` which is usually where the
-   client token is. This is done on purpose to allow application services to
-   reuse client SDKs.
+   client token is, such as via the query string or ``Authorization`` header. This 
+   is done on purpose to allow application services to reuse client SDKs.
+ - The ``access_token`` should be supplied through the ``Authorization`` header where
+   possible to prevent the token appearing in HTTP request logs by accident.
 
-::
+The application service may specify the virtual user to act as through use of a
+``user_id`` query string parameter on the request. The user specified in the query
+string must be covered by one of the application 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.
+
+An example request would be::
 
- /path?access_token=$token&user_id=$userid
+ GET /_matrix/client/%CLIENT_MAJOR_VERSION%/account/whoami?user_id=@_irc_user:example.org
+ Authorization: Bearer YourApplicationServiceTokenHere
 
- Query Parameters:
-   access_token: The application service token
-   user_id: The desired user ID to act as.
 
 Timestamp massaging
 +++++++++++++++++++
@@ -223,11 +228,10 @@ Notes:
 
 ::
 
- /path?access_token=$token&ts=$timestamp
+ PUT /_matrix/client/r0/rooms/!somewhere:domain.com/send/m.room.message/txnId?ts=1534535223283
+  Authorization: Bearer YourApplicationServiceTokenHere
 
- Query Parameters added to the send event APIs only:
-   access_token: The application service token
-   ts: The desired timestamp
+ Content: The event to send, as per the Client-Server API.
 
 Server admin style permissions
 ++++++++++++++++++++++++++++++
@@ -250,12 +254,13 @@ including the AS token on a ``/register`` request, along with a login type of
 
 ::
 
-  /register?access_token=$as_token
+  POST /_matrix/client/%CLIENT_MAJOR_VERSION%/register
+  Authorization: Bearer YourApplicationServiceTokenHere
 
   Content:
   {
     type: "m.login.application_service",
-    username: "<desired user localpart in AS namespace>"
+    username: "_irc_example"
   }
 
 Application services which attempt to create users or aliases *outside* of