Device Management

This module provides a means for a user to manage their devices.

Client behaviour

Clients that implement this module should offer the user a list of registered devices, as well as the means to update their display names. Clients should also allow users to delete disused devices.

POST /_matrix/client/v3/delete_devices

This API endpoint uses the User-Interactive Authentication API.

Deletes the given devices, and invalidates any access token associated with them.

Rate-limited:	No
Requires authentication:	Yes

Request

Request body

Name	Type	Description
`auth`	`Authentication Data`	Additional authentication information for the user-interactive authentication API.
`devices`	`[string]`	Required: The list of device IDs to delete.

Authentication Data
Name	Type	Description
`session`	`string`	The value of the session key given by the homeserver.
`type`	`string`	The authentication type that the client is attempting to complete. May be omitted if `session` is given, and the client is reissuing a request which it believes has been completed out-of-band (for example, via the fallback mechanism).

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "devices": [
    "QBUAZIFURK",
    "AUIECTSRND"
  ]
}

Responses

Status	Description
`200`	The devices were successfully removed, or had been removed previously.
`401`	The homeserver requires additional authentication information.

200 response

{}

401 response

Authentication response
Name	Type	Description
`completed`	`[string]`	A list of the stages the client has completed successfully
`flows`	`[Flow information]`	Required: A list of the login flows supported by the server for this API.
`params`	`object`	Contains any information that the client will need to know in order to use a given type of authentication. For each login type presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here.
`session`	`string`	This is a session identifier that the client must pass back to the home server, if one is provided, in subsequent attempts to authenticate in the same API call.

Flow information
Name	Type	Description
`stages`	`[string]`	Required: The login type of each of the stages required to complete this authentication flow

{
  "completed": [
    "example.type.foo"
  ],
  "flows": [
    {
      "stages": [
        "example.type.foo"
      ]
    }
  ],
  "params": {
    "example.type.baz": {
      "example_key": "foobar"
    }
  },
  "session": "xxxxxxyz"
}

GET /_matrix/client/v3/devices

Gets information about all devices for the current user.

Rate-limited:	No
Requires authentication:	Yes

Request

No request parameters or request body.

Responses

Status	Description
`200`	Device information

200 response

Name	Type	Description
`devices`	`[Device]`	A list of all registered devices for this user.

Device
Name	Type	Description
`device_id`	`string`	Required: Identifier of this device.
`display_name`	`string`	Display name set by the user for this device. Absent if no name has been set.
`last_seen_ip`	`string`	The IP address where this device was last seen. (May be a few minutes out of date, for efficiency reasons).
`last_seen_ts`	`integer`	The timestamp (in milliseconds since the unix epoch) when this devices was last seen. (May be a few minutes out of date, for efficiency reasons).

{
  "devices": [
    {
      "device_id": "QBUAZIFURK",
      "display_name": "android",
      "last_seen_ip": "1.2.3.4",
      "last_seen_ts": 1474491775024
    }
  ]
}

GET /_matrix/client/v3/devices/{deviceId}

Gets information on a single device, by device id.

Rate-limited:	No
Requires authentication:	Yes

Request

Request parameters

path parameters
Name	Type	Description
`deviceId`	`string`	Required: The device to retrieve.

Responses

Status	Description
`200`	Device information
`404`	The current user has no device with the given ID.

200 response

Device
Name	Type	Description
`device_id`	`string`	Required: Identifier of this device.
`display_name`	`string`	Display name set by the user for this device. Absent if no name has been set.
`last_seen_ip`	`string`	The IP address where this device was last seen. (May be a few minutes out of date, for efficiency reasons).
`last_seen_ts`	`integer`	The timestamp (in milliseconds since the unix epoch) when this devices was last seen. (May be a few minutes out of date, for efficiency reasons).

{
  "device_id": "QBUAZIFURK",
  "display_name": "android",
  "last_seen_ip": "1.2.3.4",
  "last_seen_ts": 1474491775024
}

PUT /_matrix/client/v3/devices/{deviceId}

Updates the metadata on the given device.

Rate-limited:	No
Requires authentication:	Yes

Request

Request parameters

path parameters
Name	Type	Description
`deviceId`	`string`	Required: The device to update.

Request body

Name	Type	Description
`display_name`	`string`	The new display name for this device. If not given, the display name is unchanged.

Request body example

{
  "display_name": "My other phone"
}

Responses

Status	Description
`200`	The device was successfully updated.
`404`	The current user has no device with the given ID.

200 response

{}

DELETE /_matrix/client/v3/devices/{deviceId}

This API endpoint uses the User-Interactive Authentication API.

Deletes the given device, and invalidates any access token associated with it.

Rate-limited:	No
Requires authentication:	Yes

Request

Request parameters

path parameters
Name	Type	Description
`deviceId`	`string`	Required: The device to delete.

Request body

Name	Type	Description
`auth`	`Authentication Data`	Additional authentication information for the user-interactive authentication API.

Authentication Data
Name	Type	Description
`session`	`string`	The value of the session key given by the homeserver.
`type`	`string`	The authentication type that the client is attempting to complete. May be omitted if `session` is given, and the client is reissuing a request which it believes has been completed out-of-band (for example, via the fallback mechanism).

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  }
}

Responses

Status	Description
`200`	The device was successfully removed, or had been removed previously.
`401`	The homeserver requires additional authentication information.

200 response

{}

401 response

Authentication response
Name	Type	Description
`completed`	`[string]`	A list of the stages the client has completed successfully
`flows`	`[Flow information]`	Required: A list of the login flows supported by the server for this API.
`params`	`object`	Contains any information that the client will need to know in order to use a given type of authentication. For each login type presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here.
`session`	`string`	This is a session identifier that the client must pass back to the home server, if one is provided, in subsequent attempts to authenticate in the same API call.

Flow information
Name	Type	Description
`stages`	`[string]`	Required: The login type of each of the stages required to complete this authentication flow

{
  "completed": [
    "example.type.foo"
  ],
  "flows": [
    {
      "stages": [
        "example.type.foo"
      ]
    }
  ],
  "params": {
    "example.type.baz": {
      "example_key": "foobar"
    }
  },
  "session": "xxxxxxyz"
}

Security considerations

Deleting devices has security implications: it invalidates the access_token assigned to the device, so an attacker could use it to log out the real user (and do it repeatedly every time the real user tries to log in to block the attacker). Servers should require additional authentication beyond the access token when deleting devices (for example, requiring that the user resubmit their password).

The display names of devices are publicly visible. Clients should consider advising the user of this.