Device management API
Richard van der Hoff
8 years ago
parent
9265b03008
commit
af515012ea
@ -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,139 @@
|
||||
# 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
|
||||
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 retrieve.
|
||||
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