Document the user-interactive api params

Document the parameters and responses on /register and /account/password which
are invoved in the user-interactive auth

api/client-server/administrative_contact.yaml

@@ -18,6 +18,8 @@ paths:
     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.
@@ -30,14 +32,15 @@ paths:
           name: body
           schema:
             type: object
-            example: |-
-              {
-                "new_password": "ihatebananas"
-              }
             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:
@@ -46,6 +49,11 @@ paths:
             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:

api/client-server/definitions/auth_data.yaml

@@ -0,0 +1,20 @@
+title: Authentication Data
+description: |-
+  Used by clients to submit authentication information to the interactive-authentication API
+type: object
+properties:
+  type:
+    description: The login type that the client is attempting to complete.
+    type: string
+  session:
+    description: The value of the session key given by the homeserver.
+    type: string
+additionalProperties:
+  description: Keys dependent on the login type
+  type: object
+required:
+  - type
+example:
+  type: "example.type.foo"
+  session: "xxxxx"
+  example_credential: "verypoorsharedsecret"

api/client-server/definitions/auth_response.yaml

@@ -0,0 +1,49 @@
+title: Authentication response
+description: |-
+  Used by servers to indicate that additional authentication information is required,
+type: object
+properties:
+  flows:
+    description: A list of the login flows supported by the server for this API.
+    title: Flow information
+    type: array
+    items:
+      type: object
+      properties:
+        stages:
+          description: |-
+            The login type of each of the stages required to complete this
+            authentication flow
+          type: array
+          items:
+            type: string
+            example: "example.type.foo"
+      required:
+        - stages
+  params:
+    type: object
+    description: |-
+      Contains any information that the client will need to know in order to
+      use a given type of authentication. For each login type presented,
+      that type may be present as a key in this dictionary. For example, the
+      public part of an OAuth client ID could be given here.
+    additionalProperties:
+      type: object
+    example:
+      "example.type.baz": { "example_key": "foobar" }
+  session:
+    type: string
+    description: |-
+      This is a session identifier that the client must pass back to the home
+      server, if one is provided, in subsequent attempts to authenticate in the
+      same API call.
+    example: "xxxxxxyz"
+  completed:
+    type: array
+    description: |-
+      A list of the stages the client has completed successfully
+    items:
+      type: string
+      example: "example.type.foo"
+required:
+  - flows

api/client-server/registration.yaml

@@ -39,26 +39,27 @@ paths:
           name: body
           schema:
             type: object
-            example: |-
-              {
-                "username": "cheeky_monkey",
-                "password": "ilovebananas",
-                "bind_email": false
-              }
             properties:
+              auth:
+                description: |-
+                  Additional authentication information for the user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
               bind_email:
                 type: boolean
                 description: |-
                   If true, the server binds the email used for authentication to
                   the Matrix ID with the ID Server.
+                example: false
               username:
                 type: string
                 description: |-
                   The local part of the desired Matrix ID. If omitted,
                   the homeserver MUST generate a Matrix ID local part.
+                example: cheeky_monkey
               password:
                 type: string
                 description: The desired password for the account.
+                example: ilovebananas
             required: ["password"]
       responses:
         200:
@@ -118,6 +119,11 @@ paths:
                   "errcode": "M_USER_IN_USE",
                   "error": "Desired user ID is already taken."
               }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
         429:
           description: This request was rate-limited.
           schema: