Clarify n-factor auth and add the diagram back in as an example

specification/10_client_server_api.rst

@@ -48,14 +48,15 @@ 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'. When all
+to authenticate itself. Each flow comprises one or more 'stages'. Flows may have
-stages are complete, authentication is complete and the API call succeeds. To
+more than one stage to implement n-factor auth. When all stages are complete,
-establish what flows a server supports for an endpoint, a client sends the
+authentication is complete and the API call succeeds. To establish what flows a
-request with no authentication. A request to an endpoint that uses
+server supports for an endpoint, a client sends the request with no
-User-Interactive Authentication never succeeds without auth. Home Servers may
+authentication. A request to an endpoint that uses User-Interactive
-allow requests that don't require auth by offering a stage with only the
+Authentication never succeeds without auth. Home Servers may allow requests that
-``m.login.dummy`` auth type. The home server returns a response with HTTP status
+don't require auth by offering a stage with only the ``m.login.dummy`` auth
-401 and a JSON object as folows::
+type. The home server returns a response with HTTP status 401 and a JSON object
+as folows::
 
   {
     "flows": [
@@ -138,6 +139,10 @@ message in the standard format::
     "error": "Something was wrong"
   }
 
+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.
+
 If the client has completed all stages of a flow, the home server performs the
 API call and returns the result as normal.
 
@@ -150,6 +155,40 @@ ie. the request will either complete or request auth, with the presence or
 absence of that login stage type in the 'completed' array indicating whether
 that stage is complete.
 
+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         |
+  | type: "<stage type1>" |
+  |  ___________________  |
+  | |_Request_1_________| | <-- Returns "session" key which is used throughout.
+  |  ___________________  |
+  | |_Request_2_________| |
+  |_______________________|
+            |
+            |
+   _________V_____________
+  |       Stage 2         |
+  | type: "<stage type2>" |
+  |  ___________________  |
+  | |_Request_1_________| |
+  |  ___________________  |
+  | |_Request_2_________| |
+  |  ___________________  |
+  | |_Request_3_________| |
+  |_______________________|
+            |
+            |
+   _________V_____________
+  |       Stage 3         |
+  | type: "<stage type3>" |
+  |  ___________________  |
+  | |_Request_1_________| | <-- Returns API response
+  |_______________________|
+
 This specification defines the following login types:
  - ``m.login.password``
  - ``m.login.recaptcha``