Add m.login.appservice to the spec (#3324)

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Hubert Chathi <hubertc@matrix.org>
Co-authored-by: Travis Ralston <travisr@matrix.org>

changelogs/client_server/newsfragments/3324.feature

@@ -0,0 +1 @@
+Extend `/_matrix/client/r0/login` to accept a `m.login.appservice`, as per [MSC2778](https://github.com/matrix-org/matrix-doc/pull/2778).

content/application-service-api.md

@@ -312,10 +312,11 @@ information.
 
 The homeserver needs to give the application service *full control* over
 its namespace, both for users and for room aliases. This means that the
-AS should be able to create/edit/delete any room alias in its namespace,
-as well as create/delete any user in its namespace. No additional API
+AS should be able to manage any users and room alias in its namespace. No additional API
 changes need to be made in order for control of room aliases to be
-granted to the AS. Creation of users needs API changes in order to:
+granted to the AS.
+
+Creation of users needs API changes in order to:
 
 -   Work around captchas.
 -   Have a 'passwordless' user.
@@ -334,8 +335,26 @@ user ID without a password.
       username: "_irc_example"
     }
 
+Similarly, logging in as users needs API changes in order to allow the AS to
+log in without needing the user's password. This is achieved by including the
+`as_token` on a `/login` request, along with a login type of
+`m.login.application_service`.
+
+    POST /_matrix/client/%CLIENT_MAJOR_VERSION%/login
+    Authorization: Bearer YourApplicationServiceTokenHere
+
+    Content:
+    {
+      type: "m.login.application_service",
+      "identifier": {
+        "type": "m.id.user",
+        "user": "_irc_example"
+      }
+    }
+
 Application services which attempt to create users or aliases *outside*
-of their defined namespaces will receive an error code `M_EXCLUSIVE`.
+of their defined namespaces, or log in as users outside of their defined
+namespaces will receive an error code `M_EXCLUSIVE`.
 Similarly, normal users who attempt to create users or aliases *inside*
 an application service-defined namespace will receive the same
 `M_EXCLUSIVE` error code, but only if the application service has

content/client-server-api/_index.md

@@ -1022,6 +1022,41 @@ client supports it, the client should redirect the user to the
 is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
+#### Appservice Login
+
+An appservice can log in by providing a valid appservice token and a user within the appservice's
+namespace. 
+
+{{% boxes/note %}}
+Appservices do not need to log in as individual users in all cases, as they
+can perform [Identity Assertion](/application-service-api#identity-assertion)
+using the appservice token. However, if the appservice needs a scoped token
+for a single user then they can use this API instead.
+{{% /boxes/note %}}
+
+This request must be authenticated by the [appservice `as_token`](/application-service-api#registration) 
+(see [Client Authentication](#client-authentication) on how to provide the token).
+
+To use this login type, clients should submit a `/login` request as follows:
+
+```json
+{
+  "type": "m.login.appservice",
+  "identifier": {
+    "type": "m.id.user",
+    "user": "<user_id or user localpart>"
+  }
+}
+```
+
+If the access token is not valid, does not correspond to an appservice
+or the user has not previously been registered then the homeserver will
+respond with an errcode of `M_FORBIDDEN`.
+
+If the access token does correspond to an appservice, but the user id does
+not lie within its namespace then the homeserver will respond with an
+errcode of `M_EXCLUSIVE`.
+
 {{% http-api spec="client-server" api="login" %}}
 
 {{% http-api spec="client-server" api="logout" %}}