Client device doc

Document client devices, and the mods to the login and register apis to support
them.

api/client-server/login.yaml

@@ -33,6 +33,14 @@ paths:
       description: |-
         Authenticates the user, and issues an access token they can
         use to authorize themself in subsequent requests.
+
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        The returned access token must be associated with the ``device_id``
+        supplied by the client or generated by the server. The server may
+        invalidate any access token previously associated with that device. See
+        `Relationship between access tokens and devices`_.
       parameters:
         - in: body
           name: body
@@ -42,7 +50,8 @@ paths:
               {
                 "type": "m.login.password",
                 "user": "cheeky_monkey",
-                "password": "ilovebananas"
+                "password": "ilovebananas",
+                "initial_device_display_name": "Jungle Phone"
               }
             properties:
               type:
@@ -67,6 +76,17 @@ paths:
                 type: string
                 description: |-
                   Required when ``type`` is ``m.login.token``. The login token.
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
             required: ["type"]
 
       responses:
@@ -77,7 +97,8 @@ paths:
               {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org"
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
               }
           schema:
             type: object
@@ -93,6 +114,11 @@ paths:
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.
+              device_id:
+                type: string
+                description: |-
+                  ID of the logged-in device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.

api/client-server/registration.yaml

@@ -42,6 +42,13 @@ paths:
         If registration is successful, this endpoint will issue an access token
         the client can use to authorize itself in subsequent requests.
 
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        The returned access token must be associated with the ``device_id``
+        supplied by the client or generated by the server. The server may
+        invalidate any access token previously associated with that device. See
+        `Relationship between access tokens and devices`_.
       parameters:
         - in: query
           name: kind
@@ -84,7 +91,19 @@ paths:
                 type: string
                 description: The desired password for the account.
                 example: ilovebananas
-            required: ["password"]
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+                example: GHTYAJCE
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
+                example: Jungle Phone
       responses:
         200:
           description: The account has been registered.
@@ -93,7 +112,8 @@ paths:
               {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org"
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
               }
           schema:
             type: object
@@ -109,6 +129,11 @@ paths:
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.
+              device_id:
+                type: string
+                description: |-
+                  ID of the registered device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
         400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:

specification/client_server_api.rst

@@ -185,6 +185,21 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
    to choose an appropriate format. Server implementors may like to investigate
    `macaroons <macaroon_>`_.
 
+Relationship between access tokens and devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Client `devices`_ are closely related to access tokens.  Matrix servers should
+record which device each access token is assigned to, so that subsequent
+requests can be handled correctly.
+
+By default, the `Login`_ and `Registration`_ processes auto-generate a new
+``device_id``. A client is also free to generate its own ``device_id`` or,
+provided the user remains the same, reuse a device: in ether case the client
+should pass the ``device_id`` in the request body. If the client sets the
+``device_id``, the server will invalidate any access token previously assigned
+to that device. There is therefore at most one active access token assigned to
+each device at any one time.
+
 User-Interactive Authentication API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1366,6 +1381,7 @@ have to wait in milliseconds before they can try again.
 .. References
 
 .. _`macaroon`: http://research.google.com/pubs/pub41892.html
+.. _`devices`: ../intro.html#devices
 
 .. Links through the external API docs are below
 .. =============================================

specification/intro.rst

@@ -160,6 +160,35 @@ allocated the account and has the form::
 See the `Identifier Grammar`_ section for full details of the structure of
 user IDs.
 
+
+Devices
+~~~~~~~
+
+The Matrix specification has a particular meaning for the term "device". As a
+user, I might have several devices: a desktop client, some web browsers, an
+Android device, an iPhone, etc. They broadly relate to a real device in the
+physical world, but you might have several browsers on a physical device, or
+several Matrix client applications on a mobile device, each of which would be
+its own device.
+
+Devices are used primarily to manage the keys used for end-to-end encryption
+(each device gets its own copy of the decryption keys), but they also help
+users manage their access - for instance, by revoking access to particular
+devices.
+
+When a user first uses a client, it registers itself as a new device. The
+longevity of devices might depend on the type of client. A web client will
+probably drop all of its state on logout, and create a new device every time
+you log in, to ensure that cryptography keys are not leaked to a new user.  In
+a mobile client, it might be acceptable to reuse the device if a login session
+expires, provided the user is the same.
+
+Devices are identified by a ``device_id``, which is unique within the scope of
+a given user.
+
+A user may assign a human-readable display name to a device, to help them
+manage their devices.
+
 Events
 ~~~~~~