commit
4abdcc6f05
@ -0,0 +1,44 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
#
|
||||||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
# you may not use this file except in compliance with the License.
|
||||||
|
# You may obtain a copy of the License at
|
||||||
|
#
|
||||||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
#
|
||||||
|
# Unless required by applicable law or agreed to in writing, software
|
||||||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
# See the License for the specific language governing permissions and
|
||||||
|
# limitations under the License.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
description: A client device
|
||||||
|
title: Device
|
||||||
|
properties:
|
||||||
|
device_id:
|
||||||
|
type: string
|
||||||
|
description: Identifier of this device.
|
||||||
|
example: QBUAZIFURK
|
||||||
|
display_name:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
Display name set by the user for this device. Absent if no name has been
|
||||||
|
set.
|
||||||
|
example: android
|
||||||
|
last_seen_ip:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The IP address where this device was last seen. (May be a few minutes out
|
||||||
|
of date, for efficiency reasons).
|
||||||
|
example: 1.2.3.4
|
||||||
|
last_seen_ts:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: |-
|
||||||
|
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).
|
||||||
|
example: 1474491775024
|
||||||
|
required:
|
||||||
|
- device_id
|
@ -0,0 +1,177 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
#
|
||||||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
# you may not use this file except in compliance with the License.
|
||||||
|
# You may obtain a copy of the License at
|
||||||
|
#
|
||||||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
#
|
||||||
|
# Unless required by applicable law or agreed to in writing, software
|
||||||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
# See the License for the specific language governing permissions and
|
||||||
|
# limitations under the License.
|
||||||
|
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server device management API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/devices":
|
||||||
|
get:
|
||||||
|
summary: List registered devices for the current user
|
||||||
|
description: |-
|
||||||
|
Gets information about all devices for the current user.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Device information
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
devices:
|
||||||
|
type: array
|
||||||
|
description: A list of all registered devices for this user.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "definitions/client_device.yaml"
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"devices": [
|
||||||
|
{
|
||||||
|
"device_id": "QBUAZIFURK",
|
||||||
|
"display_name": "android",
|
||||||
|
"last_seen_ip": "1.2.3.4",
|
||||||
|
"last_seen_ts": 1474491775024
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
tags:
|
||||||
|
- Device management
|
||||||
|
"/devices/{deviceId}":
|
||||||
|
get:
|
||||||
|
summary: Get a single device
|
||||||
|
description: |-
|
||||||
|
Gets information on a single device, by device id.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: deviceId
|
||||||
|
description: The device to retrieve.
|
||||||
|
required: true
|
||||||
|
x-example: "QBUAZIFURK"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Device information
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "definitions/client_device.yaml"
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"device_id": "QBUAZIFURK",
|
||||||
|
"display_name": "android",
|
||||||
|
"last_seen_ip": "1.2.3.4",
|
||||||
|
"last_seen_ts": 1474491775024
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: The current user has no device with the given ID.
|
||||||
|
tags:
|
||||||
|
- Device management
|
||||||
|
put:
|
||||||
|
summary: Update a device
|
||||||
|
description: |-
|
||||||
|
Updates the metadata on the given device.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: deviceId
|
||||||
|
description: The device to update.
|
||||||
|
required: true
|
||||||
|
x-example: "QBUAZIFURK"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
description: New information for the device.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
display_name:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The new display name for this device. If not given, the
|
||||||
|
display name is unchanged.
|
||||||
|
example: My other phone
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The device was successfully updated.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
schema:
|
||||||
|
type: object # empty json object
|
||||||
|
404:
|
||||||
|
description: The current user has no device with the given ID.
|
||||||
|
tags:
|
||||||
|
- Device management
|
||||||
|
delete:
|
||||||
|
summary: Delete a device
|
||||||
|
description: |-
|
||||||
|
This API endpoint uses the `User-Interactive Authentication API`_.
|
||||||
|
|
||||||
|
Deletes the given device, and invalidates any access token assoicated with it.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: deviceId
|
||||||
|
description: The device to delete.
|
||||||
|
required: true
|
||||||
|
x-example: "QBUAZIFURK"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
auth:
|
||||||
|
description: |-
|
||||||
|
Additional authentication information for the
|
||||||
|
user-interactive authentication API.
|
||||||
|
"$ref": "definitions/auth_data.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The device was successfully removed, or had been removed
|
||||||
|
previously.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
401:
|
||||||
|
description: |-
|
||||||
|
The homeserver requires additional authentication information.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/auth_response.yaml"
|
||||||
|
tags:
|
||||||
|
- Device management
|
@ -0,0 +1,41 @@
|
|||||||
|
.. Copyright 2016 OpenMarket Ltd
|
||||||
|
..
|
||||||
|
.. Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
.. you may not use this file except in compliance with the License.
|
||||||
|
.. You may obtain a copy of the License at
|
||||||
|
..
|
||||||
|
.. http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
..
|
||||||
|
.. Unless required by applicable law or agreed to in writing, software
|
||||||
|
.. distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
.. See the License for the specific language governing permissions and
|
||||||
|
.. limitations under the License.
|
||||||
|
|
||||||
|
Device Management
|
||||||
|
=================
|
||||||
|
|
||||||
|
.. _module: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.
|
||||||
|
|
||||||
|
{{device_management_cs_http_api}}
|
||||||
|
|
||||||
|
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.
|
Loading…
Reference in New Issue