Clarifications to the 'Client authentication' section

* Use the terminology 'login type' everywhere instead of mixing up 'stage type'
  and 'login type'

* Don't have a separate 'APIs using the User-Interactive Authentication
  mechanism' section, because (a) it doesn't make much sense to organise the
  APIs this way, and (b) it was a set of lies anyway.

* Move '/account/password' definition into registration.yaml so that register
  and password can share a section in the spec; remove duplicate doc for
  /password.

* Write some words on using 3pids for /login

api/client-server/administrative_contact.yaml

@@ -14,52 +14,6 @@ produces:
 securityDefinitions:
   $ref: definitions/security.yaml
 paths:
-  "/account/password":
-    post:
-      summary: Changes a user's password.
-      description: |-
-        Changes the password for an account on this homeserver.
-
-        This API endpoint uses the User-Interactive Authentication API.
-        An access token should be submitted to this endpoint if the client has
-        an active session.
-        The homeserver may change the flows available depending on whether a
-        valid access token is provided.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            properties:
-              new_password:
-                type: string
-                description: The new password for the account.
-                example: "ihatebananas"
-              auth:
-                description: |-
-                  Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
-            required: ["new_password"]
-      responses:
-        200:
-          description: The password has been changed.
-          examples:
-            application/json: "{}"
-          schema:
-            type: object
-        401:
-          description: |-
-            The homeserver requires additional authentication information.
-          schema:
-            "$ref": "definitions/auth_response.yaml"
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - User data
   "/account/3pid":
     get:
       summary: Gets a list of a user's third party identifiers.

api/client-server/registration.yaml

@@ -16,6 +16,8 @@ paths:
     post:
       summary: Register for an account on this homeserver.
       description: |-
+        This API endpoint uses the `User-Interactive Authentication API`.
+
         Register for an account on this homeserver.
 
         There are two kinds of user account:
@@ -110,7 +112,7 @@ paths:
             whilst the client was performing authentication.
 
             Homeservers MUST perform the relevant checks and return these codes before
-            performing `User-Interactive Authentication`_, although they may also return
+            performing User-Interactive Authentication, although they may also return
             them after authentication is completed if, for example, the requested user ID
             was registered whilst the client was performing authentication.
           examples:
@@ -130,3 +132,51 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - User data
+  "/account/password":
+    post:
+      summary: Changes a user's password.
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              new_password:
+                type: string
+                description: The new password for the account.
+                example: "ihatebananas"
+              auth:
+                description: |-
+                  Additional authentication information for the user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+            required: ["new_password"]
+      responses:
+        200:
+          description: The password has been changed.
+          examples:
+            application/json: "{}"
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data