|
|
|
|
# Copyright 2019-2020 The Matrix.org Foundation C.I.C.
|
|
|
|
|
#
|
|
|
|
|
# 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 Key Backup API
|
|
|
|
|
version: 1.0.0
|
|
|
|
|
paths:
|
|
|
|
|
/room_keys/version:
|
|
|
|
|
post:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Create a new backup.
|
|
|
|
|
description: Creates a new backup.
|
|
|
|
|
operationId: postRoomKeysVersion
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
requestBody:
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
algorithm:
|
|
|
|
|
description: The algorithm used for storing backups.
|
|
|
|
|
type: string
|
|
|
|
|
enum:
|
|
|
|
|
- m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
example: m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
auth_data:
|
|
|
|
|
description: |-
|
|
|
|
|
Algorithm-dependent data. See the documentation for the backup
|
|
|
|
|
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
|
|
|
|
expected format of the data.
|
|
|
|
|
type: object
|
|
|
|
|
example:
|
|
|
|
|
public_key: abcdefg
|
|
|
|
|
signatures:
|
|
|
|
|
"@alice:example.org":
|
|
|
|
|
ed25519:deviceid: signature
|
|
|
|
|
required:
|
|
|
|
|
- algorithm
|
|
|
|
|
- auth_data
|
|
|
|
|
description: The backup configuration.
|
|
|
|
|
required: true
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The version id of the new backup.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
version:
|
|
|
|
|
type: string
|
|
|
|
|
description: The backup version. This is an opaque string.
|
|
|
|
|
example: "1"
|
|
|
|
|
required:
|
|
|
|
|
- version
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
get:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Get information about the latest backup version.
|
|
|
|
|
description: Get information about the latest backup version.
|
|
|
|
|
operationId: getRoomKeysVersionCurrent
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The information about the backup.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
algorithm:
|
|
|
|
|
type: string
|
|
|
|
|
description: The algorithm used for storing backups.
|
|
|
|
|
enum:
|
|
|
|
|
- m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
example: m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
auth_data:
|
|
|
|
|
description: |-
|
|
|
|
|
Algorithm-dependent data. See the documentation for the backup
|
|
|
|
|
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
|
|
|
|
expected format of the data.
|
|
|
|
|
type: object
|
|
|
|
|
example:
|
|
|
|
|
public_key: abcdefg
|
|
|
|
|
signatures:
|
|
|
|
|
"@alice:example.org":
|
|
|
|
|
ed25519:deviceid: signature
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup.
|
|
|
|
|
type: integer
|
|
|
|
|
example: 42
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
An opaque string representing stored keys in the backup.
|
|
|
|
|
Clients can compare it with the `etag` value they received
|
|
|
|
|
in the request of their last key storage request. If not
|
|
|
|
|
equal, another client has modified the backup.
|
|
|
|
|
type: string
|
|
|
|
|
example: anopaquestring
|
|
|
|
|
version:
|
|
|
|
|
type: string
|
|
|
|
|
description: The backup version.
|
|
|
|
|
example: "1"
|
|
|
|
|
required:
|
|
|
|
|
- algorithm
|
|
|
|
|
- auth_data
|
|
|
|
|
- count
|
|
|
|
|
- etag
|
|
|
|
|
- version
|
|
|
|
|
"404":
|
|
|
|
|
description: No backup exists.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "No current backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
"/room_keys/version/{version}":
|
|
|
|
|
get:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Get information about an existing backup.
|
|
|
|
|
description: Get information about an existing backup.
|
|
|
|
|
operationId: getRoomKeysVersion
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: path
|
|
|
|
|
name: version
|
|
|
|
|
description: |-
|
|
|
|
|
The backup version to get, as returned in the `version` parameter
|
|
|
|
|
of the response in
|
|
|
|
|
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
|
|
|
|
|
or this endpoint.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The information about the requested backup.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
algorithm:
|
|
|
|
|
type: string
|
|
|
|
|
description: The algorithm used for storing backups.
|
|
|
|
|
enum:
|
|
|
|
|
- m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
example: m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
auth_data:
|
|
|
|
|
description: |-
|
|
|
|
|
Algorithm-dependent data. See the documentation for the backup
|
|
|
|
|
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
|
|
|
|
expected format of the data.
|
|
|
|
|
type: object
|
|
|
|
|
example:
|
|
|
|
|
public_key: abcdefg
|
|
|
|
|
signatures:
|
|
|
|
|
"@alice:example.org":
|
|
|
|
|
ed25519:deviceid: signature
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup.
|
|
|
|
|
type: integer
|
|
|
|
|
example: 42
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
An opaque string representing stored keys in the backup.
|
|
|
|
|
Clients can compare it with the `etag` value they received
|
|
|
|
|
in the request of their last key storage request. If not
|
|
|
|
|
equal, another client has modified the backup.
|
|
|
|
|
type: string
|
|
|
|
|
example: anopaquestring
|
|
|
|
|
version:
|
|
|
|
|
type: string
|
|
|
|
|
description: The backup version.
|
|
|
|
|
example: "1"
|
|
|
|
|
required:
|
|
|
|
|
- algorithm
|
|
|
|
|
- auth_data
|
|
|
|
|
- count
|
|
|
|
|
- etag
|
|
|
|
|
- version
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup specified does not exist.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
put:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Update information about an existing backup.
|
|
|
|
|
description: Update information about an existing backup. Only `auth_data` can
|
|
|
|
|
be modified.
|
|
|
|
|
operationId: putRoomKeysVersion
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: path
|
|
|
|
|
name: version
|
|
|
|
|
description: |-
|
|
|
|
|
The backup version to update, as returned in the `version`
|
|
|
|
|
parameter in the response of
|
|
|
|
|
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
|
|
|
|
|
or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
requestBody:
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
algorithm:
|
|
|
|
|
description: |-
|
|
|
|
|
The algorithm used for storing backups. Must be the same as
|
|
|
|
|
the algorithm currently used by the backup.
|
|
|
|
|
type: string
|
|
|
|
|
enum:
|
|
|
|
|
- m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
example: m.megolm_backup.v1.curve25519-aes-sha2
|
|
|
|
|
auth_data:
|
|
|
|
|
description: |-
|
|
|
|
|
Algorithm-dependent data. See the documentation for the backup
|
|
|
|
|
algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
|
|
|
|
|
expected format of the data.
|
|
|
|
|
type: object
|
|
|
|
|
example:
|
|
|
|
|
public_key: abcdefg
|
|
|
|
|
signatures:
|
|
|
|
|
"@alice:example.org":
|
|
|
|
|
ed25519:deviceid: signature
|
|
|
|
|
version:
|
|
|
|
|
description: |-
|
|
|
|
|
The backup version. If present, must be the same as the
|
|
|
|
|
version in the path parameter.
|
|
|
|
|
type: string
|
|
|
|
|
example: "1"
|
|
|
|
|
required:
|
|
|
|
|
- algorithm
|
|
|
|
|
- auth_data
|
|
|
|
|
description: The backup configuration
|
|
|
|
|
required: true
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {}
|
|
|
|
|
"400":
|
|
|
|
|
description: |-
|
|
|
|
|
A parameter was incorrect. For example, the `algorithm` does not
|
|
|
|
|
match the current backup algorithm, or the `version` in the body
|
|
|
|
|
does not match the `version` in the path.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_INVALID_PARAM",
|
|
|
|
|
"error": "Algorithm does not match"
|
|
|
|
|
}
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup specified does not exist.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
delete:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Delete an existing key backup.
|
|
|
|
|
description: |-
|
|
|
|
|
Delete an existing key backup. Both the information about the backup,
|
|
|
|
|
as well as all key data related to the backup will be deleted.
|
|
|
|
|
operationId: deleteRoomKeysVersion
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: path
|
|
|
|
|
name: version
|
|
|
|
|
description: |-
|
|
|
|
|
The backup version to delete, as returned in the `version`
|
|
|
|
|
parameter in the response of
|
|
|
|
|
[`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
|
|
|
|
|
or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: |-
|
|
|
|
|
The delete succeeded, or the specified backup was previously
|
|
|
|
|
deleted.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties: {}
|
|
|
|
|
"404":
|
|
|
|
|
description: |-
|
|
|
|
|
The backup specified does not exist. If the backup was previously
|
|
|
|
|
deleted, the call should succeed rather than returning an error.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
"/room_keys/keys/{roomId}/{sessionId}":
|
|
|
|
|
put:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Store a key in the backup.
|
|
|
|
|
description: Store a key in the backup.
|
|
|
|
|
operationId: putRoomKeyBySessionId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup in which to store the key. Must be the current backup.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: sessionId
|
|
|
|
|
description: The ID of the megolm session that the key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: sessionid
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
requestBody:
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/key_backup_data.yaml
|
|
|
|
|
description: The key data.
|
|
|
|
|
required: true
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"403":
|
|
|
|
|
description: |-
|
|
|
|
|
The version specified does not match the current backup version.
|
|
|
|
|
The current version will be included in the `current_version`
|
|
|
|
|
field.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
|
|
|
|
"error": "Wrong backup version.",
|
|
|
|
|
"current_version": "42"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
get:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Retrieve a key from the backup.
|
|
|
|
|
description: Retrieve a key from the backup.
|
|
|
|
|
operationId: getRoomKeyBySessionId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to retrieve the key.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the requested key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: sessionId
|
|
|
|
|
description: The ID of the megolm session whose key is requested.
|
|
|
|
|
required: true
|
|
|
|
|
example: sessionid
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The key data
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/key_backup_data.yaml
|
|
|
|
|
"404":
|
|
|
|
|
description: The key or backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Key not found."
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
delete:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Delete a key from the backup.
|
|
|
|
|
description: Delete a key from the backup.
|
|
|
|
|
operationId: deleteRoomKeyBySessionId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to delete the key
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the specified key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: sessionId
|
|
|
|
|
description: The ID of the megolm session whose key is to be deleted.
|
|
|
|
|
required: true
|
|
|
|
|
example: sessionid
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
"/room_keys/keys/{roomId}":
|
|
|
|
|
put:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Store several keys in the backup for a given room.
|
|
|
|
|
description: Store several keys in the backup for a given room.
|
|
|
|
|
operationId: putRoomKeysByRoomId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup in which to store the keys. Must be the current backup.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the keys are for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
requestBody:
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/room_key_backup.yaml
|
|
|
|
|
description: The backup data
|
|
|
|
|
required: true
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"403":
|
|
|
|
|
description: |-
|
|
|
|
|
The version specified does not match the current backup version.
|
|
|
|
|
The current version will be included in the `current_version`
|
|
|
|
|
field.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
|
|
|
|
"error": "Wrong backup version.",
|
|
|
|
|
"current_version": "42"
|
|
|
|
|
}
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
get:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Retrieve the keys from the backup for a given room.
|
|
|
|
|
description: Retrieve the keys from the backup for a given room.
|
|
|
|
|
operationId: getRoomKeysByRoomId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to retrieve the key.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the requested key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: |-
|
|
|
|
|
The key data. If no keys are found, then an object with an empty
|
|
|
|
|
`sessions` property will be returned (`{"sessions": {}}`).
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
$ref: definitions/room_key_backup.yaml
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
delete:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Delete the keys from the backup for a given room.
|
|
|
|
|
description: Delete the keys from the backup for a given room.
|
|
|
|
|
operationId: deleteRoomKeysByRoomId
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to delete the key.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
- in: path
|
|
|
|
|
name: roomId
|
|
|
|
|
description: The ID of the room that the specified key is for.
|
|
|
|
|
required: true
|
|
|
|
|
example: "!roomid:example.org"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
/room_keys/keys:
|
|
|
|
|
put:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Store several keys in the backup.
|
|
|
|
|
description: Store several keys in the backup.
|
|
|
|
|
operationId: putRoomKeys
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup in which to store the keys. Must be the current backup.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
requestBody:
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
rooms:
|
|
|
|
|
type: object
|
|
|
|
|
description: A map of room IDs to room key backup data.
|
|
|
|
|
additionalProperties:
|
|
|
|
|
$ref: definitions/room_key_backup.yaml
|
|
|
|
|
example:
|
|
|
|
|
"!room:example.org":
|
|
|
|
|
sessions:
|
|
|
|
|
sessionid1:
|
|
|
|
|
first_message_index: 1
|
|
|
|
|
forwarded_count: 0
|
|
|
|
|
is_verified: true
|
|
|
|
|
session_data:
|
|
|
|
|
ephemeral: base64+ephemeral+key
|
|
|
|
|
ciphertext: base64+ciphertext+of+JSON+data
|
|
|
|
|
mac: base64+mac+of+ciphertext
|
|
|
|
|
required:
|
|
|
|
|
- rooms
|
|
|
|
|
description: The backup data.
|
|
|
|
|
required: true
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"403":
|
|
|
|
|
description: |-
|
|
|
|
|
The version specified does not match the current backup version.
|
|
|
|
|
The current version will be included in the `current_version`
|
|
|
|
|
field.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
|
|
|
|
"error": "Wrong backup version.",
|
|
|
|
|
"current_version": "42"
|
|
|
|
|
}
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
get:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Retrieve the keys from the backup.
|
|
|
|
|
description: Retrieve the keys from the backup.
|
|
|
|
|
operationId: getRoomKeys
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to retrieve the keys.
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: |-
|
|
|
|
|
The key data. If no keys are found, then an object with an empty
|
|
|
|
|
`rooms` property will be returned (`{"rooms": {}}`).
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
rooms:
|
|
|
|
|
type: object
|
|
|
|
|
description: A map of room IDs to room key backup data.
|
|
|
|
|
additionalProperties:
|
|
|
|
|
$ref: definitions/room_key_backup.yaml
|
|
|
|
|
example:
|
|
|
|
|
"!room:example.org":
|
|
|
|
|
sessions:
|
|
|
|
|
sessionid1:
|
|
|
|
|
first_message_index: 1
|
|
|
|
|
forwarded_count: 0
|
|
|
|
|
is_verified: true
|
|
|
|
|
session_data:
|
|
|
|
|
ephemeral: base64+ephemeral+key
|
|
|
|
|
ciphertext: base64+ciphertext+of+JSON+data
|
|
|
|
|
mac: base64+mac+of+ciphertext
|
|
|
|
|
required:
|
|
|
|
|
- rooms
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version."
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
delete:
|
|
|
|
|
x-addedInMatrixVersion: "1.1"
|
|
|
|
|
summary: Delete the keys from the backup.
|
|
|
|
|
description: Delete the keys from the backup.
|
|
|
|
|
operationId: deleteRoomKeys
|
|
|
|
|
security:
|
|
|
|
|
- accessTokenQuery: []
|
|
|
|
|
- accessTokenBearer: []
|
|
|
|
|
parameters:
|
|
|
|
|
- in: query
|
|
|
|
|
name: version
|
|
|
|
|
description: The backup from which to delete the key
|
|
|
|
|
required: true
|
|
|
|
|
example: "1"
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: The update succeeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
type: object
|
|
|
|
|
title: RoomKeysUpdateResponse
|
|
|
|
|
properties:
|
|
|
|
|
etag:
|
|
|
|
|
description: |-
|
|
|
|
|
The new etag value representing stored keys in the backup.
|
|
|
|
|
See `GET /room_keys/version/{version}` for more details.
|
|
|
|
|
type: string
|
|
|
|
|
example: abcdefg
|
|
|
|
|
count:
|
|
|
|
|
description: The number of keys stored in the backup
|
|
|
|
|
type: integer
|
|
|
|
|
example: 10
|
|
|
|
|
required:
|
|
|
|
|
- etag
|
|
|
|
|
- count
|
|
|
|
|
"404":
|
|
|
|
|
description: The backup was not found.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/error.yaml
|
|
|
|
|
examples:
|
|
|
|
|
response:
|
|
|
|
|
value: {
|
|
|
|
|
"errcode": "M_NOT_FOUND",
|
|
|
|
|
"error": "Unknown backup version"
|
|
|
|
|
}
|
|
|
|
|
"429":
|
|
|
|
|
description: This request was rate-limited.
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: definitions/errors/rate_limited.yaml
|
|
|
|
|
tags:
|
|
|
|
|
- End-to-end encryption
|
|
|
|
|
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
|
