Merge pull request #69 from matrix-org/erikj/login_token

m.login.token

specification/1-client_server_api.rst

@@ -197,6 +197,7 @@ This specification defines the following login types:
  - ``m.login.recaptcha``
  - ``m.login.oauth2``
  - ``m.login.email.identity``
+ - ``m.login.token``
  - ``m.login.dummy``
 
 Password-based
@@ -228,6 +229,37 @@ To respond to this type, reply with an auth dict as follows::
     "response": "<captcha response>"
   }
 
+Token-based
+~~~~~~~~~~~
+:Type:
+  ``m.login.token``
+:Description:
+  The client submits a username and token.
+
+To respond to this type, reply with an auth dict as follows::
+
+  {
+    "type": "m.login.token",
+    "user": "<user_id or user localpart>",
+    "token": "<token>",
+    "txn_id": "<client generated nonce>"
+  }
+
+The ``nonce`` should be a random string generated by the client for the
+request. The same ``nonce`` should be used if retrying the request.
+
+There are many ways a client may receive a ``token``, including via an email or
+from an existing logged in device.
+
+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 ``token`` must be a macaroon.
+
 OAuth2-based
 ~~~~~~~~~~~~
 :Type: