Rename nonce to txn_id. Reorganize for clarity.
@@ -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
<<<<<<<<<<<<
