Client device doc
Document client devices, and the mods to the login and register apis to support them.
This commit is contained in:
Richard van der Hoff
parent
2b0b5ffeb8
commit
9265b03008
4 changed files with 100 additions and 4 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
.. =============================================
|
||||
|
|
|
|||
|
|
@ -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
|
||||
~~~~~~
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue