Clarifications to authentication mechanisms

* Make the purpose of the `auth` key in /register requests explicit, and say
  that it should be empty at first.

* Restructure the UA-auth section a bit.

* In the UA-auth section, say that clients should submit no `auth` to start
  with, and add 'Stage 0' representing  this to the example.

* s/{stage,login} type/authentication type/ in the UA-auth section. Seems
   clearer to me.

* Try to distinguish the example responses from the example requests by giving
  an HTTP header.

api/client-server/registration.yaml

@@ -29,7 +29,7 @@ paths:
     post:
       summary: Register for an account on this homeserver.
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`.
+        This API endpoint uses the `User-Interactive Authentication API`_.
 
         Register for an account on this homeserver.
 
@@ -57,7 +57,13 @@ paths:
             properties:
               auth:
                 description: |-
-                  Additional authentication information for the user-interactive authentication API.
+                    Additional authentication information for the
+                    user-interactive authentication API. Note that this
+                    information is *not* used to define how the registered user
+                    should be authenticated, but is instead used to
+                    authenticate the ``register`` call itself. It should be
+                    left empty, or omitted, unless an earlier call returned an
+                    response with status code 401.
                 "$ref": "definitions/auth_data.yaml"
               bind_email:
                 type: boolean

specification/client_server_api.rst

@@ -169,6 +169,9 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
 User-Interactive Authentication API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Overview
+<<<<<<<<
+
 Some API endpoints require authentication that
 interacts with the user. The homeserver may provide many different ways of
 authenticating, such as user/password auth, login via a social network (OAuth2),
@@ -177,26 +180,31 @@ does not define how homeservers should authorise their users but instead
 defines the standard interface which implementations should follow so that ANY
 client can login to ANY homeserver.
 
-The process takes the form of one or more stages, where at each stage the client
+The process takes the form of one or more 'stages'. At each stage the client
-submits a set of data for a given stage type and awaits a response from the
+submits a set of data for a given authentication type and awaits a response
-server, which will either be a final success or a request to perform an
+from the server, which will either be a final success or a request to perform
-additional stage. This exchange continues until the final success.
+an additional stage. This exchange continues until the final success.
-
-Authentication works by client and server exchanging dictionaries. This
-specification covers how this is done over JSON HTTP POST.
-
-For each endpoint, a server offers one of more 'flows' that the client can use
-to authenticate itself. Each flow comprises one or more 'stages'. Flows may have
-more than one stage to implement n-factor auth. When all stages are complete,
-authentication is complete and the API call succeeds. To establish what flows a
-server supports for an endpoint, a client sends the request with no
-authentication. A request to an endpoint that uses User-Interactive
-Authentication never succeeds without auth. Homeservers may allow requests that
-don't require auth by offering a stage with only the ``m.login.dummy`` auth
-type. The homeserver returns a response with HTTP status 401 and a JSON object
-as follows:
 
-.. code:: json
+For each endpoint, a server offers one or more 'flows' that the client can use
+to authenticate itself. Each flow comprises a series of stages, as described
+above. The client is free to choose which flow it follows. When all stages in a
+flow are complete, authentication is complete and the API call succeeds.
+
+User-interactive API in the REST API
+<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+
+In the REST API described in this specification, authentication works by the
+client and server exchanging JSON dictionaries. The server indicates what
+authentication data it requires via the body of an HTTP 401 response, and the
+client submits that authentication data via the ``auth`` request parameter.
+
+A client should first make a request with no ``auth`` parameter [#]_. The
+homeserver returns an HTTP 401 response, with a JSON body, as follows:
+
+.. code::
+
+  HTTP/1.1 401 Unauthorized
+  Content-Type: application/json
 
   {
     "flows": [
@@ -220,7 +228,7 @@ information:
 
 params
   This section contains any information that the client will need to know in
-  order to use a given type of authentication. For each login type
+  order to use a given type of authentication. For each authentication 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.
 session
@@ -231,14 +239,17 @@ session
 The client then chooses a flow and attempts to complete one of the stages. It
 does this by resubmitting the same request with the addition of an ``auth``
 key in the object that it submits. This dictionary contains a ``type`` key whose
-value is the name of the login type that the client is attempting to complete.
+value is the name of the authentication type that the client is attempting to complete.
 It must also contain a ``session`` key with the value of the session key given
 by the homeserver, if one was given. It also contains other keys dependent on
-the login type being attempted. For example, if the client is attempting to
+the auth type being attempted. For example, if the client is attempting to
-complete login type ``example.type.foo``, it might submit something like this:
+complete auth type ``example.type.foo``, it might submit something like this:
 
-.. code:: json
+.. code::
 
+  POST /_matrix/client/r0/endpoint HTTP/1.1
+  Content-Type: application/json
+  
   {
     "a_request_parameter": "something",
     "another_request_parameter": "something else",
@@ -252,10 +263,13 @@ complete login type ``example.type.foo``, it might submit something like this:
 If the homeserver deems the authentication attempt to be successful but still
 requires more stages to be completed, it returns HTTP status 401 along with the
 same object as when no authentication was attempted, with the addition of the
-``completed`` key which is an array of login types the client has completed
+``completed`` key which is an array of auth types the client has completed
 successfully:
 
-.. code:: json
+.. code::
+
+  HTTP/1.1 401 Unauthorized
+  Content-Type: application/json
 
   {
     "completed": [ "example.type.foo" ],
@@ -278,7 +292,10 @@ successfully:
 If the homeserver decides the attempt was unsuccessful, it returns an error
 message in the standard format:
 
-.. code:: json
+.. code::
+
+  HTTP/1.1 400 Bad request
+  Content-Type: application/json
 
   {
     "errcode": "M_EXAMPLE_ERROR",
@@ -287,7 +304,7 @@ message in the standard format:
 
 Individual stages may require more than one request to complete, in which case
 the response will be as if the request was unauthenticated with the addition of
-any other keys as defined by the login type.
+any other keys as defined by the auth type.
 
 If the client has completed all stages of a flow, the homeserver performs the
 API call and returns the result as normal.
@@ -298,27 +315,38 @@ clicks on the link in the email. In this case, the client retries the request
 with an auth dict containing only the session key. The response to this will be
 the same as if the client were attempting to complete an auth state normally,
 i.e. the request will either complete or request auth, with the presence or
-absence of that login type in the 'completed' array indicating whether
+absence of that auth type in the 'completed' array indicating whether
 that stage is complete.
 
+.. [#] A request to an endpoint that uses User-Interactive Authentication never
+       succeeds without auth. Homeservers may allow requests that don't require
+       auth by offering a stage with only the ``m.login.dummy`` auth type, but
+       they must still give a 401 response to requests with no auth data.
+
 Example
 +++++++
 At a high level, the requests made for an API call completing an auth flow with
 three stages will resemble the following diagram::
 
    _______________________
-  |       Stage 1         |
+  |       Stage 0         |
-  | type: "<login type1>" |
+  | No auth               |
   |  ___________________  |
   | |_Request_1_________| | <-- Returns "session" key which is used throughout.
+  |_______________________|
+            |
+            |
+   _________V_____________
+  |       Stage 1         |
+  | type: "<auth type1>"  |
   |  ___________________  |
-  | |_Request_2_________| |
+  | |_Request_1_________| |
   |_______________________|
             |
             |
    _________V_____________
   |       Stage 2         |
-  | type: "<login type2>" |
+  | type: "<auth type2>"  |
   |  ___________________  |
   | |_Request_1_________| |
   |  ___________________  |
@@ -330,16 +358,16 @@ three stages will resemble the following diagram::
             |
    _________V_____________
   |       Stage 3         |
-  | type: "<login type3>" |
+  | type: "<auth type3>"  |
   |  ___________________  |
   | |_Request_1_________| | <-- Returns API response
   |_______________________|
 
 
-Login types
+Authentication types
-+++++++++++
+++++++++++++++++++++
 
-This specification defines the following login types:
+This specification defines the following auth types:
  - ``m.login.password``
  - ``m.login.recaptcha``
  - ``m.login.oauth2``
@@ -354,7 +382,7 @@ Password-based
 :Description:
   The client submits a username and secret password, both sent in plain-text.
 
-To respond to this type, reply with an auth dict as follows:
+To use this authentication type, clients should submit an auth dict as follows:
 
 .. code:: json
 
@@ -393,7 +421,7 @@ Google ReCaptcha
 :Description:
   The user completes a Google ReCaptcha 2.0 challenge
 
-To respond to this type, reply with an auth dict as follows:
+To use this authentication type, clients should submit an auth dict as follows:
 
 .. code:: json
 
@@ -409,7 +437,7 @@ Token-based
 :Description:
   The client submits a login token.
 
-To respond to this type, reply with an auth dict as follows:
+To use this authentication type, clients should submit an auth dict as follows:
 
 .. code:: json
 
@@ -471,7 +499,7 @@ Prior to submitting this, the client should authenticate with an identity
 server. After authenticating, the session information should be submitted to
 the homeserver.
 
-To respond to this type, reply with an auth dict as follows:
+To use this authentication type, clients should submit an auth dict as follows:
 
 .. code:: json
 
@@ -495,8 +523,8 @@ Dummy Auth
   purpose is to allow servers to not require any form of User-Interactive
   Authentication to perform a request.
 
-To respond to this type, reply with an auth dict with just the type and session,
+To use this authentication type, clients should submit an auth dict with just
-if provided:
+the type and session, if provided:
 
 .. code:: json
 
@@ -513,9 +541,9 @@ the user to a web browser with the URL of a fallback page which will allow the
 user to complete that login step out-of-band in their web browser. The URL it
 should open is::
 
-  /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<stage type>/fallback/web?session=<session ID>
+  /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID>
 
-Where ``stage type`` is the type name of the stage it is attempting and
+Where ``auth type`` is the type name of the stage it is attempting and
 ``session id`` is the ID of the session given by the homeserver.
 
 This MUST return an HTML page which can perform this authentication stage. This
@@ -527,8 +555,11 @@ Login
 
 A client can obtain access tokens using the ``/login`` API.
 
-For a simple username/password login, a client should submit an auth dict as
+Note that this endpoint does `not` currently use the user-interactive
-follows:
+authentication API.
+
+For a simple username/password login, clients should submit a ``/login``
+request as follows:
 
 .. code:: json
 
@@ -554,7 +585,8 @@ explicitly, as follows:
 In the case that the homeserver does not know about the supplied 3pid, the
 homeserver must respond with ``403 Forbidden``.
 
-To log in using a login token, a client should submit an auth dict as follows:
+To log in using a login token, clients should submit a ``/login`` request as
+follows:
 
 .. code:: json