mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-20 08:38:36 +01:00
7c39427d8b
Some checks failed
Spec / 🔎 Validate OpenAPI specifications (push) Has been cancelled
Spec / 🔎 Check Event schema examples (push) Has been cancelled
Spec / 🔎 Check OpenAPI definitions examples (push) Has been cancelled
Spec / 🔎 Check JSON Schemas inline examples (push) Has been cancelled
Spec / ⚙️ Calculate baseURL for later jobs (push) Has been cancelled
Spec / 📢 Run towncrier for changelog (push) Has been cancelled
Spell Check / Spell Check with Typos (push) Has been cancelled
Spec / 🐍 Build OpenAPI definitions (push) Has been cancelled
Spec / 📖 Build the spec (push) Has been cancelled
Spec / 🔎 Validate generated HTML (push) Has been cancelled
Spec / 📖 Build the historical backup spec (push) Has been cancelled
As per MSC4190. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
301 lines
9.7 KiB
YAML
301 lines
9.7 KiB
YAML
# 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.
|
|
openapi: 3.1.0
|
|
info:
|
|
title: Matrix Client-Server device management API
|
|
version: 1.0.0
|
|
paths:
|
|
/devices:
|
|
get:
|
|
summary: List registered devices for the current user
|
|
description: Gets information about all devices for the current user.
|
|
operationId: getDevices
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
responses:
|
|
"200":
|
|
description: Device information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
devices:
|
|
type: array
|
|
description: A list of all registered devices for this user.
|
|
items:
|
|
$ref: definitions/client_device.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"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.
|
|
operationId: getDevice
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
parameters:
|
|
- in: path
|
|
name: deviceId
|
|
description: The device to retrieve.
|
|
required: true
|
|
example: QBUAZIFURK
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Device information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/client_device.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"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: Create or update a device
|
|
x-changedInMatrixVersion:
|
|
"1.17": The ability to create new devices was added.
|
|
description: |-
|
|
Updates the metadata on the given device, or creates a new device.
|
|
|
|
The ability to create new devices is only available to application
|
|
services: regular clients may only update existing devices.
|
|
|
|
When a new device was created, the homeserver MUST return a 201 HTTP
|
|
status code. It MUST return a 200 HTTP status code if a device was
|
|
updated.
|
|
|
|
This endpoint is rate-limited for device creation. Servers MAY use login
|
|
rate limits.
|
|
operationId: updateDevice
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
parameters:
|
|
- in: path
|
|
name: deviceId
|
|
description: The device to update.
|
|
required: true
|
|
example: QBUAZIFURK
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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: {
|
|
"display_name": "My other phone"
|
|
}
|
|
description: New information for the device.
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The device was successfully updated.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object # empty json object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"201":
|
|
description: |-
|
|
The device was successfully created by the application service.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"404":
|
|
description: The current user has no device with the given ID.
|
|
tags:
|
|
- Device management
|
|
delete:
|
|
summary: Delete a device
|
|
x-changedInMatrixVersion:
|
|
"1.17": |-
|
|
This endpoint no longer requires User-Interactive Authentication when used by an
|
|
application service.
|
|
description: |-
|
|
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
|
except when used by an application service.
|
|
|
|
Deletes the given device, and invalidates any access token associated with it.
|
|
|
|
{{% boxes/warning %}}
|
|
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
|
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
|
{{% /boxes/warning %}}
|
|
operationId: deleteDevice
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
parameters:
|
|
- in: path
|
|
name: deviceId
|
|
description: The device to delete.
|
|
required: true
|
|
example: QBUAZIFURK
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the
|
|
user-interactive authentication API.
|
|
allOf:
|
|
- $ref: definitions/auth_data.yaml
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The device was successfully removed, or had been removed
|
|
previously.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"401":
|
|
description: The homeserver requires additional authentication information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/auth_response.yaml
|
|
tags:
|
|
- Device management
|
|
/delete_devices:
|
|
post:
|
|
summary: Bulk deletion of devices
|
|
x-changedInMatrixVersion:
|
|
"1.17": |-
|
|
This endpoint no longer requires User-Interactive Authentication when used by an
|
|
application service.
|
|
description: |-
|
|
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
|
except when used by an application service.
|
|
|
|
Deletes the given devices, and invalidates any access token associated with them.
|
|
|
|
{{% boxes/warning %}}
|
|
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
|
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
|
{{% /boxes/warning %}}
|
|
operationId: deleteDevices
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
devices:
|
|
type: array
|
|
description: The list of device IDs to delete.
|
|
items:
|
|
type: string
|
|
description: A list of device IDs.
|
|
example:
|
|
- QBUAZIFURK
|
|
- AUIECTSRND
|
|
auth:
|
|
allOf:
|
|
- $ref: definitions/auth_data.yaml
|
|
description: |-
|
|
Additional authentication information for the
|
|
user-interactive authentication API.
|
|
required:
|
|
- devices
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The devices were successfully removed, or had been removed
|
|
previously.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
response:
|
|
value: {}
|
|
"401":
|
|
description: The homeserver requires additional authentication information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/auth_response.yaml
|
|
tags:
|
|
- Device management
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8008
|
|
basePath:
|
|
default: /_matrix/client/v3
|
|
components:
|
|
securitySchemes:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|