Merge pull request #2369 from iinuwa/token-auth-doc-tweaks

Rename nonce to txn_id. Reorganize for clarity.

changelogs/client_server/newsfragments/2369.clarification

@@ -0,0 +1 @@
+Minor clarifications to token-based User-Interactive Authentication.

specification/client_server_api.rst

@@ -740,22 +740,23 @@ To use this authentication type, clients should submit an auth dict as follows:
     "session": "<session ID>"
   }
 
-The ``nonce`` should be a random string generated by the client for the
-request. The same ``nonce`` should be used if retrying the request.
 
 A client may receive a login ``token`` via some external service, such as email
 or SMS. Note that a login token is separate from an access token, the latter
 providing general authentication to various API endpoints.
 
-The ``txn_id`` may be used by the server to disallow other devices from using
-the token, thus providing "single use" tokens while still allowing the device
-to retry the request. This would be done by tying the token to the ``txn_id``
+Additionally, the server must encode the user ID in the ``token``; there is
+therefore no need for the client to submit a separate username.
+
+The ``txn_id`` should be a random string generated by the client for the
+request. The same ``txn_id`` should be used if retrying the request. The
+``txn_id`` may be used by the server to disallow other devices from using the
+token, thus providing "single use" tokens while still allowing the device to
+retry the request. This would be done by tying the token to the ``txn_id``
 server side, as well as potentially invalidating the token completely once the
 device has successfully logged in (e.g. when we receive a request from the
 newly provisioned access_token).
 
-The server must encode the user id in the ``token``. There is therefore no need
-for the client to submit a separate username.
 
 OAuth2-based
 <<<<<<<<<<<<