diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index 7731f507..8c0282be 100644 --- a/api/client-server/login.yaml +++ b/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. diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 8145824e..756004c1 100644 --- a/api/client-server/registration.yaml +++ b/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: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2645b1d8..d445e482 100644 --- a/specification/client_server_api.rst +++ b/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 `_. +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 .. ============================================= diff --git a/specification/intro.rst b/specification/intro.rst index 0ecfdec5..5d0587f2 100644 --- a/specification/intro.rst +++ b/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 ~~~~~~