Merge branch 'master' into travis/msc/integrations/openid
Travis Ralston
4 years ago
commit
df74c7dbe3
@ -0,0 +1,16 @@
|
|||||||
|
steps:
|
||||||
|
- label: ":books: Build spec"
|
||||||
|
command:
|
||||||
|
- python3 -m venv env
|
||||||
|
- env/bin/pip install -r scripts/requirements.txt
|
||||||
|
- ". env/bin/activate; scripts/generate-matrix-org-assets"
|
||||||
|
artifact_paths:
|
||||||
|
- assets.tar.gz
|
||||||
|
plugins:
|
||||||
|
- docker#v3.0.1:
|
||||||
|
image: "python:3.6"
|
||||||
|
|
||||||
|
- label: "rebuild matrix.org"
|
||||||
|
trigger: "matrix-dot-org"
|
||||||
|
async: true
|
||||||
|
branches: "master"
|
||||||
@ -0,0 +1,2 @@
|
|||||||
|
patreon: matrixdotorg
|
||||||
|
liberapay: matrixdotorg
|
||||||
@ -0,0 +1,19 @@
|
|||||||
|
---
|
||||||
|
name: Proposal ready for review
|
||||||
|
about: A proposal that is ready for review by the core team and community.
|
||||||
|
title: ''
|
||||||
|
labels: proposal, proposal-in-review
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- Put your "rendered" link here -->
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
|
||||||
|
* [ ] Pull request title and file name include this PR's number as the MSC number.
|
||||||
@ -0,0 +1,16 @@
|
|||||||
|
---
|
||||||
|
name: Spec clarification/not a proposal
|
||||||
|
about: A change that's not a spec proposal, such as a clarification to the spec itself.
|
||||||
|
title: ''
|
||||||
|
labels: ''
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)
|
||||||
@ -0,0 +1,20 @@
|
|||||||
|
---
|
||||||
|
name: WIP Proposal
|
||||||
|
about: A proposal that isn't quite ready for formal review yet.
|
||||||
|
title: '[WIP] Your Proposal Title'
|
||||||
|
labels: proposal
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- Put your "rendered" link here -->
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
|
||||||
|
* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
|
||||||
|
* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.
|
||||||
@ -0,0 +1,50 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: KeyBackupData
|
||||||
|
description: "The key data"
|
||||||
|
properties:
|
||||||
|
first_message_index:
|
||||||
|
description: |-
|
||||||
|
The index of the first message in the session that the key can decrypt.
|
||||||
|
type: integer
|
||||||
|
example: 1
|
||||||
|
forwarded_count:
|
||||||
|
description: |-
|
||||||
|
The number of times this key has been forwarded via key-sharing between devices.
|
||||||
|
type: integer
|
||||||
|
example: 0
|
||||||
|
is_verified:
|
||||||
|
description: |-
|
||||||
|
Whether the device backing up the key verified the device that the key
|
||||||
|
is from.
|
||||||
|
type: boolean
|
||||||
|
example: false
|
||||||
|
session_data:
|
||||||
|
description: |-
|
||||||
|
Algorithm-dependent data. See the documentation for the backup
|
||||||
|
algorithms in `Server-side key backups`_ for more information on the
|
||||||
|
expected format of the data.
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"ephemeral": "base64+ephemeral+key",
|
||||||
|
"ciphertext": "base64+ciphertext+of+JSON+data",
|
||||||
|
"mac": "base64+mac+of+ciphertext"
|
||||||
|
}
|
||||||
|
required:
|
||||||
|
- first_message_index
|
||||||
|
- forwarded_count
|
||||||
|
- is_verified
|
||||||
|
- session_data
|
||||||
@ -0,0 +1,36 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
access_token:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An access token the consumer may use to verify the identity of
|
||||||
|
the person who generated the token. This is given to the federation
|
||||||
|
API ``GET /openid/userinfo`` to verify the user's identity.
|
||||||
|
token_type:
|
||||||
|
type: string
|
||||||
|
description: The string ``Bearer``.
|
||||||
|
matrix_server_name:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The homeserver domain the consumer should use when attempting to
|
||||||
|
verify the user's identity.
|
||||||
|
expires_in:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
The number of seconds before this token expires and a new one must
|
||||||
|
be generated.
|
||||||
|
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
|
||||||
@ -0,0 +1,36 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "../../identity/definitions/request_email_validation.yaml"
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
id_server:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The hostname of the identity server to communicate with. May optionally
|
||||||
|
include a port. This parameter is ignored when the homeserver handles
|
||||||
|
3PID verification.
|
||||||
|
|
||||||
|
This parameter is deprecated with a plan to be removed in a future specification
|
||||||
|
version for ``/account/password`` and ``/register`` requests.
|
||||||
|
example: "id.example.com"
|
||||||
|
id_access_token:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An access token previously registered with the identity server. Servers
|
||||||
|
can treat this as optional to distinguish between r0.5-compatible clients
|
||||||
|
and this specification version.
|
||||||
|
|
||||||
|
Required if an ``id_server`` is supplied.
|
||||||
@ -0,0 +1,36 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "../../identity/definitions/request_msisdn_validation.yaml"
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
id_server:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The hostname of the identity server to communicate with. May optionally
|
||||||
|
include a port. This parameter is ignored when the homeserver handles
|
||||||
|
3PID verification.
|
||||||
|
|
||||||
|
This parameter is deprecated with a plan to be removed in a future specification
|
||||||
|
version for ``/account/password`` and ``/register`` requests.
|
||||||
|
example: "id.example.com"
|
||||||
|
id_access_token:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An access token previously registered with the identity server. Servers
|
||||||
|
can treat this as optional to distinguish between r0.5-compatible clients
|
||||||
|
and this specification version.
|
||||||
|
|
||||||
|
Required if an ``id_server`` is supplied.
|
||||||
@ -0,0 +1,37 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The session ID. Session IDs are opaque strings that must consist entirely
|
||||||
|
of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255
|
||||||
|
characters and they must not be empty.
|
||||||
|
example: "123abc"
|
||||||
|
submit_url:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An optional field containing a URL where the client must submit the
|
||||||
|
validation token to, with identical parameters to the Identity Service
|
||||||
|
API's ``POST /validate/email/submitToken`` endpoint (without the requirement
|
||||||
|
for an access token). The homeserver must send this token to the user (if
|
||||||
|
applicable), who should then be prompted to provide it to the client.
|
||||||
|
|
||||||
|
If this field is not present, the client can assume that verification
|
||||||
|
will happen without the client's involvement provided the homeserver
|
||||||
|
advertises this specification version in the ``/versions`` response
|
||||||
|
(ie: r0.5.0).
|
||||||
|
example: "https://example.org/path/to/submitToken"
|
||||||
|
required: ['sid']
|
||||||
@ -0,0 +1,38 @@
|
|||||||
|
# Copyright 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.
|
||||||
|
|
||||||
|
type: object
|
||||||
|
title: RoomKeyBackup
|
||||||
|
description: "The backed up keys for a room."
|
||||||
|
properties:
|
||||||
|
sessions:
|
||||||
|
type: object
|
||||||
|
description: "A map of session IDs to key data."
|
||||||
|
additionalProperties:
|
||||||
|
allOf:
|
||||||
|
- $ref: "key_backup_data.yaml"
|
||||||
|
example: {
|
||||||
|
"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:
|
||||||
|
- sessions
|
||||||
@ -0,0 +1,45 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
title: Third Party Signed
|
||||||
|
description: |-
|
||||||
|
A signature of an ``m.third_party_invite`` token to prove that this user
|
||||||
|
owns a third party identity which has been invited to the room.
|
||||||
|
properties:
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The Matrix ID of the user who issued the invite.
|
||||||
|
example: "@alice:example.org"
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix ID of the invitee.
|
||||||
|
example: "@bob:example.org"
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The state key of the m.third_party_invite event.
|
||||||
|
example: "random8nonce"
|
||||||
|
signatures:
|
||||||
|
type: object
|
||||||
|
description: A signatures object containing a signature of the entire signed object.
|
||||||
|
title: Signatures
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
additionalProperties:
|
||||||
|
type: string
|
||||||
|
example: {
|
||||||
|
"example.org": {
|
||||||
|
"ed25519:0": "some9signature"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
required: ["sender", "mxid", "token", "signatures"]
|
||||||
@ -0,0 +1,924 @@
|
|||||||
|
# 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server Key Backup 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:
|
||||||
|
"/room_keys/version":
|
||||||
|
post:
|
||||||
|
summary: Create a new backup.
|
||||||
|
description: |-
|
||||||
|
Creates a new backup.
|
||||||
|
operationId: postRoomKeysVersion
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: version
|
||||||
|
description: "The backup configuration."
|
||||||
|
required: true
|
||||||
|
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`_ 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
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The version id of the new backup.
|
||||||
|
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.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
get:
|
||||||
|
summary: Get information about the latest backup version.
|
||||||
|
description: |-
|
||||||
|
Get information about the latest backup version.
|
||||||
|
operationId: getRoomKeysVersionCurrent
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The information about the backup.
|
||||||
|
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`_ 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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "No current backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
"/room_keys/version/{version}":
|
||||||
|
get:
|
||||||
|
summary: Get information about an existing backup.
|
||||||
|
description: |-
|
||||||
|
Get information about an existing backup.
|
||||||
|
operationId: getRoomKeysVersion
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup version to get, as returned in the ``version`` parameter
|
||||||
|
of the response in `POST /_matrix/client/r0/room_keys/version`_ or
|
||||||
|
this endpoint.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The information about the requested backup.
|
||||||
|
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`_ 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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
put:
|
||||||
|
summary: Update information about an existing backup.
|
||||||
|
description: |-
|
||||||
|
Update information about an existing backup. Only ``auth_data`` can be modified.
|
||||||
|
operationId: putRoomKeysVersion
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup version to update, as returned in the ``version``
|
||||||
|
parameter in the response of `POST
|
||||||
|
/_matrix/client/r0/room_keys/version`_ or `GET
|
||||||
|
/_matrix/client/r0/room_keys/version/{version}`_.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: body
|
||||||
|
name: version
|
||||||
|
description: "The backup configuration"
|
||||||
|
required: true
|
||||||
|
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`_ 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
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties: {}
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_INVALID_PARAM",
|
||||||
|
"error": "Algorithm does not match"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
404:
|
||||||
|
description: The backup specified does not exist.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
delete:
|
||||||
|
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:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup version to delete, as returned in the ``version``
|
||||||
|
parameter in the response of `POST
|
||||||
|
/_matrix/client/r0/room_keys/version`_ or `GET
|
||||||
|
/_matrix/client/r0/room_keys/version/{version}`_.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The delete succeeded, or the specified backup was previously
|
||||||
|
deleted.
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
"/room_keys/keys/{roomId}/{sessionId}":
|
||||||
|
put:
|
||||||
|
summary: Store a key in the backup.
|
||||||
|
description: |-
|
||||||
|
Store a key in the backup.
|
||||||
|
operationId: postRoomKeysKeyRoomIdSessionId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup in which to store the key. Must be the current backup.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: sessionId
|
||||||
|
description: The ID of the megolm session that the key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "sessionid"
|
||||||
|
- in: body
|
||||||
|
name: data
|
||||||
|
description: "The key data."
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/key_backup_data.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||||
|
"error": "Wrong backup version.",
|
||||||
|
"current_version": "42"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
get:
|
||||||
|
summary: Retrieve a key from the backup
|
||||||
|
description: |-
|
||||||
|
Retrieve a key from the backup.
|
||||||
|
operationId: getRoomKeysKeyRoomIdSessionId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to retrieve the key.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the requested key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: sessionId
|
||||||
|
description: The ID of the megolm session whose key is requested.
|
||||||
|
required: true
|
||||||
|
x-example: "sessionid"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The key data
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/key_backup_data.yaml"
|
||||||
|
404:
|
||||||
|
description: The key or backup was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Key not found."
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
delete:
|
||||||
|
summary: Delete a key from the backup
|
||||||
|
description: |-
|
||||||
|
Delete a key from the backup.
|
||||||
|
operationId: deleteRoomKeysKeyRoomIdSessionId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to delete the key
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the specified key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: sessionId
|
||||||
|
description: The ID of the megolm session whose key is to be deleted.
|
||||||
|
required: true
|
||||||
|
x-example: "sessionid"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
"/room_keys/keys/{roomId}":
|
||||||
|
put:
|
||||||
|
summary: Store several keys in the backup for a given room.
|
||||||
|
description: |-
|
||||||
|
Store a key in the backup.
|
||||||
|
operationId: postRoomKeysKeyRoomId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup in which to store the keys. Must be the current backup.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the keys are for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
- in: body
|
||||||
|
description: "The backup data"
|
||||||
|
name: backupData
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/room_key_backup.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||||
|
"error": "Wrong backup version.",
|
||||||
|
"current_version": "42"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
The backup was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
get:
|
||||||
|
summary: Retrieve the keys from the backup for a given room
|
||||||
|
description: |-
|
||||||
|
Retrieve the keys from the backup for a given room
|
||||||
|
operationId: getRoomKeysKeyRoomId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to retrieve the key.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the requested key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The key data. If no keys are found, then an object with an empty
|
||||||
|
``sessions`` property will be returned (``{"sessions": {}}``).
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
$ref: "definitions/room_key_backup.yaml"
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
The backup was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
delete:
|
||||||
|
summary: Delete a key from the backup
|
||||||
|
description: |-
|
||||||
|
Delete a key from the backup.
|
||||||
|
operationId: deleteRoomKeysKeyRoomId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to delete the key.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The ID of the room that the specified key is for.
|
||||||
|
required: true
|
||||||
|
x-example: "!roomid:example.org"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
"/room_keys/keys":
|
||||||
|
put:
|
||||||
|
summary: Store several keys in the backup.
|
||||||
|
description: |-
|
||||||
|
Store several keys in the backup.
|
||||||
|
operationId: postRoomKeysKey
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup in which to store the keys. Must be the current backup.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
- in: body
|
||||||
|
description: "The backup data."
|
||||||
|
name: backupData
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
rooms:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
A map of room IDs to room key backup data.
|
||||||
|
additionalProperties:
|
||||||
|
allOf:
|
||||||
|
- $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
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
|
||||||
|
"error": "Wrong backup version.",
|
||||||
|
"current_version": "42"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
The backup was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
tags:
|
||||||
|
- End-to-end encryption
|
||||||
|
get:
|
||||||
|
summary: Retrieve the keys from the backup for a given room
|
||||||
|
description: |-
|
||||||
|
Retrieve the keys from the backup for a given room
|
||||||
|
operationId: getRoomKeysKeyRoomId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to retrieve the keys.
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The key data. If no keys are found, then an object with an empty
|
||||||
|
``rooms`` property will be returned (``{"rooms": {}}``).
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
rooms:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
A map of room IDs to room key backup data.
|
||||||
|
additionalProperties:
|
||||||
|
allOf:
|
||||||
|
- $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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: The backup was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version."
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
|
delete:
|
||||||
|
summary: Delete a key from the backup
|
||||||
|
description: |-
|
||||||
|
Delete a key from the backup.
|
||||||
|
operationId: deleteRoomKeysKeyRoomId
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: version
|
||||||
|
description: |-
|
||||||
|
The backup from which to delete the key
|
||||||
|
required: true
|
||||||
|
x-example: "1"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The update succeeded
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
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.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "Unknown backup version"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/error.yaml"
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/errors/rate_limited.yaml"
|
||||||
@ -0,0 +1,18 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
accessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The access_token returned by a call to ``/register``.
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
@ -0,0 +1,333 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Establishing Associations API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/3pid/getValidated3pid":
|
||||||
|
get:
|
||||||
|
summary: Check whether ownership of a 3pid was validated.
|
||||||
|
description: |-
|
||||||
|
Determines if a given 3pid has been validated by a user.
|
||||||
|
operationId: getValidated3pidV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: sid
|
||||||
|
description: The Session ID generated by the ``requestToken`` call.
|
||||||
|
required: true
|
||||||
|
x-example: 1234
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: client_secret
|
||||||
|
description: The client secret passed to the ``requestToken`` call.
|
||||||
|
required: true
|
||||||
|
x-example: monkeys_are_GREAT
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Validation information for the session.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"medium": "email",
|
||||||
|
"validated_at": 1457622739026,
|
||||||
|
"address": "louise@bobs.burgers"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The medium type of the 3pid.
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The address of the 3pid being looked up.
|
||||||
|
validated_at:
|
||||||
|
type: integer
|
||||||
|
description: |-
|
||||||
|
Timestamp, in milliseconds, indicating the time that the 3pid
|
||||||
|
was validated.
|
||||||
|
required: ['medium', 'address', 'validated_at']
|
||||||
|
400:
|
||||||
|
description: |-
|
||||||
|
The session has not been validated.
|
||||||
|
|
||||||
|
If the session has not been validated, then ``errcode`` will be
|
||||||
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
||||||
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
||||||
|
"error": "This validation session has not yet been completed"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
404:
|
||||||
|
description: The Session ID or client secret were not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NO_VALID_SESSION",
|
||||||
|
"error": "No valid session was found matching that sid and client secret"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/3pid/bind":
|
||||||
|
post:
|
||||||
|
summary: Publish an association between a session and a Matrix user ID.
|
||||||
|
description: |-
|
||||||
|
Publish an association between a session and a Matrix user ID.
|
||||||
|
|
||||||
|
Future calls to ``/lookup`` for any of the session\'s 3pids will return
|
||||||
|
this association.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with previous drafts of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: bindV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"mxid": "@ears:matrix.org"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The Session ID generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret passed to the ``requestToken`` call.
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID to associate with the 3pids.
|
||||||
|
required: ["sid", "client_secret", "mxid"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The association was published.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"address": "louise@bobs.burgers",
|
||||||
|
"medium": "email",
|
||||||
|
"mxid": "@ears:matrix.org",
|
||||||
|
"not_before": 1428825849161,
|
||||||
|
"not_after": 4582425849161,
|
||||||
|
"ts": 1428825849161,
|
||||||
|
"signatures": {
|
||||||
|
"matrix.org": {
|
||||||
|
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The 3pid address of the user being looked up.
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The medium type of the 3pid.
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID associated with the 3pid.
|
||||||
|
not_before:
|
||||||
|
type: integer
|
||||||
|
description: A unix timestamp before which the association is not known to be valid.
|
||||||
|
not_after:
|
||||||
|
type: integer
|
||||||
|
description: A unix timestamp after which the association is not known to be valid.
|
||||||
|
ts:
|
||||||
|
type: integer
|
||||||
|
description: The unix timestamp at which the association was verified.
|
||||||
|
signatures:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
The signatures of the verifying identity servers which show that the
|
||||||
|
association should be trusted, if you trust the verifying identity
|
||||||
|
services.
|
||||||
|
$ref: "../../schemas/server-signatures.yaml"
|
||||||
|
required:
|
||||||
|
- address
|
||||||
|
- medium
|
||||||
|
- mxid
|
||||||
|
- not_before
|
||||||
|
- not_after
|
||||||
|
- ts
|
||||||
|
- signatures
|
||||||
|
400:
|
||||||
|
description: |-
|
||||||
|
The association was not published.
|
||||||
|
|
||||||
|
If the session has not been validated, then ``errcode`` will be
|
||||||
|
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
|
||||||
|
``errcode`` will be ``M_SESSION_EXPIRED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_SESSION_NOT_VALIDATED",
|
||||||
|
"error": "This validation session has not yet been completed"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
404:
|
||||||
|
description: The Session ID or client secret were not found
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NO_VALID_SESSION",
|
||||||
|
"error": "No valid session was found matching that sid and client secret"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/3pid/unbind":
|
||||||
|
post:
|
||||||
|
summary: Remove an association between a session and a Matrix user ID.
|
||||||
|
description: |-
|
||||||
|
Remove an association between a session and a Matrix user ID.
|
||||||
|
|
||||||
|
Future calls to ``/lookup`` for any of the session's 3pids will not
|
||||||
|
return the removed association.
|
||||||
|
|
||||||
|
The identity server should authenticate the request in one of two
|
||||||
|
ways:
|
||||||
|
|
||||||
|
1. The request is signed by the homeserver which controls the ``user_id``.
|
||||||
|
2. The request includes the ``sid`` and ``client_secret`` parameters,
|
||||||
|
as per ``/3pid/bind``, which proves ownership of the 3PID.
|
||||||
|
|
||||||
|
If this endpoint returns a JSON Matrix error, that error should be passed
|
||||||
|
through to the client requesting an unbind through a homeserver, if the
|
||||||
|
homeserver is acting on behalf of a client.
|
||||||
|
operationId: unbindV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"mxid": "@ears:example.org",
|
||||||
|
"threepid": {
|
||||||
|
"medium": "email",
|
||||||
|
"address": "monkeys_have_ears@example.org"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The Session ID generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret passed to the ``requestToken`` call.
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID to remove from the 3pids.
|
||||||
|
threepid:
|
||||||
|
type: object
|
||||||
|
title: 3PID
|
||||||
|
description: |-
|
||||||
|
The 3PID to remove. Must match the 3PID used to generate the session
|
||||||
|
if using ``sid`` and ``client_secret`` to authenticate this request.
|
||||||
|
properties:
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
A medium from the `3PID Types`_ Appendix, matching the medium
|
||||||
|
of the identifier to unbind.
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The 3PID address to remove.
|
||||||
|
required: ['medium', 'address']
|
||||||
|
required: ["threepid", "mxid"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The association was successfully removed.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
400:
|
||||||
|
description: |-
|
||||||
|
If the response body is not a JSON Matrix error, the identity server
|
||||||
|
does not support unbinds. If a JSON Matrix error is in the response
|
||||||
|
body, the requesting party should respect the error.
|
||||||
|
404:
|
||||||
|
description: |-
|
||||||
|
If the response body is not a JSON Matrix error, the identity server
|
||||||
|
does not support unbinds. If a JSON Matrix error is in the response
|
||||||
|
body, the requesting party should respect the error.
|
||||||
|
403:
|
||||||
|
description: |-
|
||||||
|
The credentials supplied to authenticate the request were invalid.
|
||||||
|
This may also be returned if the identity server does not support
|
||||||
|
the chosen authentication method (such as blocking homeservers from
|
||||||
|
unbinding identifiers).
|
||||||
|
|
||||||
|
Another common error code is ``M_TERMS_NOT_SIGNED`` where the user
|
||||||
|
needs to `agree to more terms`_ in order to continue.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_FORBIDDEN",
|
||||||
|
"error": "Invalid homeserver signature"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
501:
|
||||||
|
description: |-
|
||||||
|
If the response body is not a JSON Matrix error, the identity server
|
||||||
|
does not support unbinds. If a JSON Matrix error is in the response
|
||||||
|
body, the requesting party should respect the error.
|
||||||
@ -0,0 +1,131 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Authentication API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/account/register":
|
||||||
|
post:
|
||||||
|
summary: Exchanges an OpenID token for an access token.
|
||||||
|
description: |-
|
||||||
|
Exchanges an OpenID token from the homeserver for an access token to
|
||||||
|
access the identity server. The request body is the same as the values
|
||||||
|
returned by ``/openid/request_token`` in the Client-Server API.
|
||||||
|
operationId: registerAccount
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/openid_token.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
A token which can be used to authenticate future requests to the
|
||||||
|
identity server.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"token": "abc123_OpaqueString"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
An opaque string representing the token to authenticate future
|
||||||
|
requests to the identity server with.
|
||||||
|
required: ['token']
|
||||||
|
"/account":
|
||||||
|
get:
|
||||||
|
summary: Gets account holder information for a given token.
|
||||||
|
description: |-
|
||||||
|
Gets information about what user owns the access token used in the request.
|
||||||
|
operationId: getAccount
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The token holder's information.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"user_id": "@alice:example.org"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: The user ID which registered the token.
|
||||||
|
required: ['user_id']
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/account/logout":
|
||||||
|
post:
|
||||||
|
summary: Logs out an access token, rendering it unusable.
|
||||||
|
description: |-
|
||||||
|
Logs out the access token, preventing it from being used to authenticate
|
||||||
|
future requests to the server.
|
||||||
|
operationId: logout
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The token was successfully logged out.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
401:
|
||||||
|
description: |-
|
||||||
|
The token is not registered or is otherwise unknown to the server.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_UNKNOWN_TOKEN",
|
||||||
|
"error": "Unrecognised access token"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,216 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Email Associations API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/validate/email/requestToken":
|
||||||
|
post:
|
||||||
|
summary: Request a token for validating an email address.
|
||||||
|
description: |-
|
||||||
|
Create a session for validating an email address.
|
||||||
|
|
||||||
|
The identity server will send an email containing a token. If that
|
||||||
|
token is presented to the identity server in the future, it indicates
|
||||||
|
that that user was able to read the email for that email address, and
|
||||||
|
so we validate ownership of the email address.
|
||||||
|
|
||||||
|
Note that homeservers offer APIs that proxy this API, adding
|
||||||
|
additional behaviour on top, for example,
|
||||||
|
``/register/email/requestToken`` is designed specifically for use when
|
||||||
|
registering an account and therefore will inform the user if the email
|
||||||
|
address given is already registered on the server.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with previous drafts of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: emailRequestTokenV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/request_email_validation.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Session created.
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/sid.yaml"
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error ocurred. Some possible errors are:
|
||||||
|
|
||||||
|
- ``M_INVALID_EMAIL``: The email address provided was invalid.
|
||||||
|
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_INVALID_EMAIL",
|
||||||
|
"error": "The email address is not valid"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/validate/email/submitToken":
|
||||||
|
post:
|
||||||
|
summary: Validate ownership of an email address.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of an email address.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the email address is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the email address with any Matrix user ID. Specifically,
|
||||||
|
calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
The identity server is free to match the token case-insensitively, or
|
||||||
|
carry out other mapping operations such as unicode
|
||||||
|
normalisation. Whether to do so is an implementation detail for the
|
||||||
|
identity server. Clients must always pass on the token without
|
||||||
|
modification.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with previous drafts of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: emailSubmitTokenPostV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"token": "atoken"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token generated by the ``requestToken`` call and emailed to the user.
|
||||||
|
required: ["sid", "client_secret", "token"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The success of the validation.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the validation was successful or not.
|
||||||
|
required: ['success']
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
get:
|
||||||
|
summary: Validate ownership of an email address.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of an email address.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the email address is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the email address with any Matrix user ID. Specifically,
|
||||||
|
calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
Note that, in contrast with the POST version, this endpoint will be
|
||||||
|
used by end-users, and so the response should be human-readable.
|
||||||
|
operationId: emailSubmitTokenGetV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: sid
|
||||||
|
required: true
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
x-example: 1234
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: client_secret
|
||||||
|
required: true
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
x-example: monkeys_are_GREAT
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: token
|
||||||
|
required: true
|
||||||
|
description: The token generated by the ``requestToken`` call and emailed to the user.
|
||||||
|
x-example: atoken
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Email address is validated.
|
||||||
|
"3xx":
|
||||||
|
description: |-
|
||||||
|
Email address is validated, and the ``next_link`` parameter was
|
||||||
|
provided to the ``requestToken`` call. The user must be redirected
|
||||||
|
to the URL provided by the ``next_link`` parameter.
|
||||||
|
"4xx":
|
||||||
|
description:
|
||||||
|
Validation failed.
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,112 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Ephemeral Invitation Signing API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/sign-ed25519":
|
||||||
|
post:
|
||||||
|
summary: Sign invitation details
|
||||||
|
description: |-
|
||||||
|
Sign invitation details.
|
||||||
|
|
||||||
|
The identity server will look up ``token`` which was stored in a call
|
||||||
|
to ``store-invite``, and fetch the sender of the invite.
|
||||||
|
operationId: blindlySignStuffV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"mxid": "@foo:bar.com",
|
||||||
|
"token": "sometoken",
|
||||||
|
"private_key": "base64encodedkey"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user accepting the invitation.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token from the call to ``store-invite``.
|
||||||
|
private_key:
|
||||||
|
type: string
|
||||||
|
description: The private key, encoded as `Unpadded base64`_.
|
||||||
|
required: ["mxid", "token", "private_key"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The signed JSON of the mxid, sender, and token.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
mxid:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user accepting the invitation.
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the user who sent the invitation.
|
||||||
|
signatures:
|
||||||
|
type: object
|
||||||
|
description: The signature of the mxid, sender, and token.
|
||||||
|
$ref: "../../schemas/server-signatures.yaml"
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token for the invitation.
|
||||||
|
required: ['mxid', 'sender', 'signatures', 'token']
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"mxid": "@foo:bar.com",
|
||||||
|
"sender": "@baz:bar.com",
|
||||||
|
"signatures": {
|
||||||
|
"my.id.server": {
|
||||||
|
"ed25519:0": "def987"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"token": "abc123"
|
||||||
|
}
|
||||||
|
404:
|
||||||
|
description: The token was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_UNRECOGNIZED",
|
||||||
|
"error": "Didn't recognize token"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,148 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2017 Kamax.io
|
||||||
|
# Copyright 2017 New Vector Ltd
|
||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Lookup API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/hash_details":
|
||||||
|
get:
|
||||||
|
summary: Gets hash function information from the server.
|
||||||
|
description: |-
|
||||||
|
Gets parameters for hashing identifiers from the server. This can include
|
||||||
|
any of the algorithms defined in this specification.
|
||||||
|
operationId: getHashDetails
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The hash function information.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"lookup_pepper": "matrixrocks",
|
||||||
|
"algorithms": ["none", "sha256"]
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
lookup_pepper:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The pepper the client MUST use in hashing identifiers, and MUST
|
||||||
|
supply to the ``/lookup`` endpoint when performing lookups.
|
||||||
|
|
||||||
|
Servers SHOULD rotate this string often.
|
||||||
|
algorithms:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The algorithms the server supports. Must contain at least ``sha256``.
|
||||||
|
required: ['lookup_pepper', 'algorithms']
|
||||||
|
"/lookup":
|
||||||
|
post:
|
||||||
|
summary: Look up Matrix User IDs for a set of 3PIDs.
|
||||||
|
description: |-
|
||||||
|
Looks up the set of Matrix User IDs which have bound the 3PIDs given, if
|
||||||
|
bindings are available. Note that the format of the addresses is defined
|
||||||
|
later in this specification.
|
||||||
|
operationId: lookupUsersV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The algorithm the client is using to encode the ``addresses``. This
|
||||||
|
should be one of the available options from ``/hash_details``.
|
||||||
|
example: "sha256"
|
||||||
|
pepper:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The pepper from ``/hash_details``. This is required even when the
|
||||||
|
``algorithm`` does not make use of it.
|
||||||
|
example: "matrixrocks"
|
||||||
|
addresses:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The addresses to look up. The format of the entries here depend on
|
||||||
|
the ``algorithm`` used. Note that queries which have been incorrectly
|
||||||
|
hashed or formatted will lead to no matches.
|
||||||
|
example: [
|
||||||
|
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
|
||||||
|
"nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
|
||||||
|
]
|
||||||
|
required: ['algorithm', 'pepper', 'addresses']
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The associations for any matched ``addresses``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"mappings": {
|
||||||
|
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
mappings:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
Any applicable mappings of ``addresses`` to Matrix User IDs. Addresses
|
||||||
|
which do not have associations will not be included, which can make
|
||||||
|
this property be an empty object.
|
||||||
|
title: AssociatedMappings
|
||||||
|
additionalProperties:
|
||||||
|
type: string
|
||||||
|
required: ['mappings']
|
||||||
|
400:
|
||||||
|
description:
|
||||||
|
The client's request was invalid in some way. One possible problem could
|
||||||
|
be the ``pepper`` being invalid after the server has rotated it - this is
|
||||||
|
presented with the ``M_INVALID_PEPPER`` error code. Clients SHOULD make
|
||||||
|
a call to ``/hash_details`` to get a new pepper in this scenario, being
|
||||||
|
careful to avoid retry loops.
|
||||||
|
|
||||||
|
``M_INVALID_PARAM`` can also be returned to indicate the client supplied
|
||||||
|
an ``algorithm`` that is unknown to the server.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_INVALID_PEPPER",
|
||||||
|
"error": "Unknown or invalid pepper - has it been rotated?"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,218 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Phone Number Associations API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/validate/msisdn/requestToken":
|
||||||
|
post:
|
||||||
|
summary: Request a token for validating a phone number.
|
||||||
|
description: |-
|
||||||
|
Create a session for validating a phone number.
|
||||||
|
|
||||||
|
The identity server will send an SMS message containing a token. If
|
||||||
|
that token is presented to the identity server in the future, it
|
||||||
|
indicates that that user was able to read the SMS for that phone
|
||||||
|
number, and so we validate ownership of the phone number.
|
||||||
|
|
||||||
|
Note that homeservers offer APIs that proxy this API, adding
|
||||||
|
additional behaviour on top, for example,
|
||||||
|
``/register/msisdn/requestToken`` is designed specifically for use when
|
||||||
|
registering an account and therefore will inform the user if the phone
|
||||||
|
number given is already registered on the server.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with previous drafts of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: msisdnRequestTokenV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/request_msisdn_validation.yaml"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Session created.
|
||||||
|
schema:
|
||||||
|
$ref: "definitions/sid.yaml"
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error ocurred. Some possible errors are:
|
||||||
|
|
||||||
|
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
|
||||||
|
- ``M_SEND_ERROR``: The validation SMS could not be sent.
|
||||||
|
- ``M_DESTINATION_REJECTED``: The identity server cannot deliver an
|
||||||
|
SMS to the provided country or region.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_INVALID_ADDRESS",
|
||||||
|
"error": "The phone number is not valid"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/validate/msisdn/submitToken":
|
||||||
|
post:
|
||||||
|
summary: Validate ownership of a phone number.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of a phone number.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the phone number is considered to
|
||||||
|
have been validated. This does not publish any information publicly, or
|
||||||
|
associate the phone number address with any Matrix user
|
||||||
|
ID. Specifically, calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
The identity server is free to match the token case-insensitively, or
|
||||||
|
carry out other mapping operations such as unicode
|
||||||
|
normalisation. Whether to do so is an implementation detail for the
|
||||||
|
identity server. Clients must always pass on the token without
|
||||||
|
modification.
|
||||||
|
|
||||||
|
Note: for backwards compatibility with previous drafts of this
|
||||||
|
specification, the parameters may also be specified as
|
||||||
|
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||||
|
deprecated.
|
||||||
|
operationId: msisdnSubmitTokenPostV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"sid": "1234",
|
||||||
|
"client_secret": "monkeys_are_GREAT",
|
||||||
|
"token": "atoken"
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
sid:
|
||||||
|
type: string
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
client_secret:
|
||||||
|
type: string
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: The token generated by the ``requestToken`` call and sent to the user.
|
||||||
|
required: ["sid", "client_secret", "token"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The success of the validation.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the validation was successful or not.
|
||||||
|
required: ['success']
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
get:
|
||||||
|
summary: Validate ownership of a phone number.
|
||||||
|
description: |-
|
||||||
|
Validate ownership of a phone number.
|
||||||
|
|
||||||
|
If the three parameters are consistent with a set generated by a
|
||||||
|
``requestToken`` call, ownership of the phone number address is
|
||||||
|
considered to have been validated. This does not publish any
|
||||||
|
information publicly, or associate the phone number with any Matrix
|
||||||
|
user ID. Specifically, calls to ``/lookup`` will not show a binding.
|
||||||
|
|
||||||
|
Note that, in contrast with the POST version, this endpoint will be
|
||||||
|
used by end-users, and so the response should be human-readable.
|
||||||
|
operationId: msisdnSubmitTokenGetV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: sid
|
||||||
|
required: true
|
||||||
|
description: The session ID, generated by the ``requestToken`` call.
|
||||||
|
x-example: 1234
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: client_secret
|
||||||
|
required: true
|
||||||
|
description: The client secret that was supplied to the ``requestToken`` call.
|
||||||
|
x-example: monkeys_are_GREAT
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: token
|
||||||
|
required: true
|
||||||
|
description: The token generated by the ``requestToken`` call and sent to the user.
|
||||||
|
x-example: atoken
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Phone number is validated.
|
||||||
|
"3xx":
|
||||||
|
description: |-
|
||||||
|
Phone number address is validated, and the ``next_link`` parameter
|
||||||
|
was provided to the ``requestToken`` call. The user must be
|
||||||
|
redirected to the URL provided by the ``next_link`` parameter.
|
||||||
|
"4xx":
|
||||||
|
description:
|
||||||
|
Validation failed.
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,46 @@
|
|||||||
|
# Copyright 2018 Kamax Sàrl
|
||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
|
||||||
|
swagger: "2.0"
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Ping API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/v2":
|
||||||
|
get:
|
||||||
|
summary: Checks that an identity server is available at this API endpoint.
|
||||||
|
description: |-
|
||||||
|
Checks that an identity server is available at this API endpoint.
|
||||||
|
|
||||||
|
To discover that an identity server is available at a specific URL,
|
||||||
|
this endpoint can be queried and will return an empty object.
|
||||||
|
|
||||||
|
This is primarly used for auto-discovery and health check purposes
|
||||||
|
by entities acting as a client for the identity server.
|
||||||
|
operationId: pingV2
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: An identity server is ready to serve requests.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
@ -0,0 +1,127 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Public Key API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/pubkey/{keyId}":
|
||||||
|
get:
|
||||||
|
summary: Get a public key.
|
||||||
|
description: |-
|
||||||
|
Get the public key for the passed key ID.
|
||||||
|
operationId: getPubKeyV2
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: keyId
|
||||||
|
required: true
|
||||||
|
description: |-
|
||||||
|
The ID of the key. This should take the form algorithm:identifier
|
||||||
|
where algorithm identifies the signing algorithm, and the identifier
|
||||||
|
is an opaque string.
|
||||||
|
x-example: "ed25519:0"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The public key exists.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
public_key:
|
||||||
|
type: string
|
||||||
|
description: Unpadded Base64 encoded public key.
|
||||||
|
required: ['public_key']
|
||||||
|
404:
|
||||||
|
description:
|
||||||
|
The public key was not found.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_NOT_FOUND",
|
||||||
|
"error": "The public key was not found"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
"/pubkey/isvalid":
|
||||||
|
get:
|
||||||
|
summary: Check whether a long-term public key is valid.
|
||||||
|
description: |-
|
||||||
|
Check whether a long-term public key is valid. The response should always
|
||||||
|
be the same, provided the key exists.
|
||||||
|
operationId: isPubKeyValidV2
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: public_key
|
||||||
|
required: true
|
||||||
|
description: |-
|
||||||
|
The unpadded base64-encoded public key to check.
|
||||||
|
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The validity of the public key.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"valid": true
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
valid:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the public key is recognised and is currently valid.
|
||||||
|
required: ['valid']
|
||||||
|
"/pubkey/ephemeral/isvalid":
|
||||||
|
get:
|
||||||
|
summary: Check whether a short-term public key is valid.
|
||||||
|
description: |-
|
||||||
|
Check whether a short-term public key is valid.
|
||||||
|
operationId: isEphemeralPubKeyValidV2
|
||||||
|
parameters:
|
||||||
|
- in: query
|
||||||
|
type: string
|
||||||
|
name: public_key
|
||||||
|
required: true
|
||||||
|
description: |-
|
||||||
|
The unpadded base64-encoded public key to check.
|
||||||
|
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The validity of the public key.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"valid": true
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
valid:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the public key is recognised and is currently valid.
|
||||||
|
required: ['valid']
|
||||||
@ -0,0 +1,176 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Store Invitations API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/store-invite":
|
||||||
|
post:
|
||||||
|
summary: Store pending invitations to a user's 3pid.
|
||||||
|
description: |-
|
||||||
|
Store pending invitations to a user's 3pid.
|
||||||
|
|
||||||
|
In addition to the request parameters specified below, an arbitrary
|
||||||
|
number of other parameters may also be specified. These may be used in
|
||||||
|
the invite message generation described below.
|
||||||
|
|
||||||
|
The service will generate a random token and an ephemeral key used for
|
||||||
|
accepting the invite.
|
||||||
|
|
||||||
|
The service also generates a ``display_name`` for the inviter, which is
|
||||||
|
a redacted version of ``address`` which does not leak the full contents
|
||||||
|
of the ``address``.
|
||||||
|
|
||||||
|
The service records persistently all of the above information.
|
||||||
|
|
||||||
|
It also generates an email containing all of this data, sent to the
|
||||||
|
``address`` parameter, notifying them of the invitation.
|
||||||
|
|
||||||
|
Also, the generated ephemeral public key will be listed as valid on
|
||||||
|
requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``.
|
||||||
|
|
||||||
|
Currently, invites may only be issued for 3pids of the ``email`` medium.
|
||||||
|
|
||||||
|
Optional fields in the request should be populated to the best of the
|
||||||
|
server's ability. Identity servers may use these variables when notifying
|
||||||
|
the ``address`` of the pending invite for display purposes.
|
||||||
|
operationId: storeInviteV2
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
medium:
|
||||||
|
type: string
|
||||||
|
description: The literal string ``email``.
|
||||||
|
example: "email"
|
||||||
|
address:
|
||||||
|
type: string
|
||||||
|
description: The email address of the invited user.
|
||||||
|
example: "foo@example.com"
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: The Matrix room ID to which the user is invited
|
||||||
|
example: "!something:example.org"
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The Matrix user ID of the inviting user
|
||||||
|
example: "@bob:example.com"
|
||||||
|
room_alias:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The Matrix room alias for the room to which the user is
|
||||||
|
invited. This should be retrieved from the ``m.room.canonical_alias``
|
||||||
|
state event.
|
||||||
|
example: "#somewhere:exmaple.org"
|
||||||
|
room_avatar_url:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The Content URI for the room to which the user is invited. This should
|
||||||
|
be retrieved from the ``m.room.avatar`` state event.
|
||||||
|
example: "mxc://example.org/s0meM3dia"
|
||||||
|
room_join_rules:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The ``join_rule`` for the room to which the user is invited. This should
|
||||||
|
be retrieved from the ``m.room.join_rules`` state event.
|
||||||
|
example: "public"
|
||||||
|
room_name:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The name of the room to which the user is invited. This should be retrieved
|
||||||
|
from the ``m.room.name`` state event.
|
||||||
|
example: "Bob's Emporium of Messages"
|
||||||
|
sender_display_name:
|
||||||
|
type: string
|
||||||
|
description: The display name of the user ID initiating the invite.
|
||||||
|
example: "Bob Smith"
|
||||||
|
sender_avatar_url:
|
||||||
|
type: string
|
||||||
|
description: The Content URI for the avatar of the user ID initiating the invite.
|
||||||
|
example: "mxc://example.org/an0th3rM3dia"
|
||||||
|
required: ["medium", "address", "room_id", "sender"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The invitation was stored.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: |
|
||||||
|
The generated token. Must be a string consisting of the
|
||||||
|
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
|
||||||
|
255 characters and it must not be empty.
|
||||||
|
public_keys:
|
||||||
|
type: array
|
||||||
|
description: |
|
||||||
|
A list of [server's long-term public key, generated ephemeral
|
||||||
|
public key].
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
display_name:
|
||||||
|
type: string
|
||||||
|
description: The generated (redacted) display_name.
|
||||||
|
required: ['token', 'public_keys', 'display_name']
|
||||||
|
example:
|
||||||
|
application/json: {
|
||||||
|
"token": "sometoken",
|
||||||
|
"public_keys": [
|
||||||
|
"serverpublickey",
|
||||||
|
"ephemeralpublickey"
|
||||||
|
],
|
||||||
|
"display_name": "f...@b..."
|
||||||
|
}
|
||||||
|
400:
|
||||||
|
description: |
|
||||||
|
An error has occured.
|
||||||
|
|
||||||
|
If the 3pid is already bound to a Matrix user ID, the error code
|
||||||
|
will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the
|
||||||
|
error code will be ``M_UNRECOGNIZED``.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_THREEPID_IN_USE",
|
||||||
|
"error": "Binding already known",
|
||||||
|
"mxid": "@alice:example.com"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
|
403:
|
||||||
|
description: |
|
||||||
|
The user must do something in order to use this endpoint. One example
|
||||||
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"errcode": "M_TERMS_NOT_SIGNED",
|
||||||
|
"error": "Please accept our updated terms of service before continuing"
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
$ref: "../client-server/definitions/errors/error.yaml"
|
||||||
@ -0,0 +1,149 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Identity Service Terms of Service API"
|
||||||
|
version: "2.0.0"
|
||||||
|
host: localhost:8090
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/identity/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/terms":
|
||||||
|
get:
|
||||||
|
summary: Gets the terms of service offered by the server.
|
||||||
|
description: |-
|
||||||
|
Gets all the terms of service offered by the server. The client is expected
|
||||||
|
to filter through the terms to determine which terms need acceptance from the
|
||||||
|
user. Note that this endpoint does not require authentication.
|
||||||
|
operationId: getTerms
|
||||||
|
parameters: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The terms of service offered by the server.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"policies": {
|
||||||
|
"terms_of_service": {
|
||||||
|
"version": "2.0",
|
||||||
|
"en": {
|
||||||
|
"name": "Terms of Service",
|
||||||
|
"url": "https://example.org/somewhere/terms-2.0-en.html"
|
||||||
|
},
|
||||||
|
"fr": {
|
||||||
|
"name": "Conditions d'utilisation",
|
||||||
|
"url": "https://example.org/somewhere/terms-2.0-fr.html"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"privacy_policy": {
|
||||||
|
"version": "1.2",
|
||||||
|
"en": {
|
||||||
|
"name": "Privacy Policy",
|
||||||
|
"url": "https://example.org/somewhere/privacy-1.2-en.html"
|
||||||
|
},
|
||||||
|
"fr": {
|
||||||
|
"name": "Politique de confidentialité",
|
||||||
|
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
policies:
|
||||||
|
type: object
|
||||||
|
title: Policy Map
|
||||||
|
description: |-
|
||||||
|
The policies the server offers. Mapped from arbitrary ID (unused in
|
||||||
|
this version of the specification) to a Policy Object.
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: Policy Object
|
||||||
|
description: |-
|
||||||
|
The policy. Includes a map of language (ISO 639-2) to language-specific
|
||||||
|
policy information.
|
||||||
|
properties:
|
||||||
|
version:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The version for the policy. There are no requirements on what this
|
||||||
|
might be and could be "alpha", semantically versioned, or arbitrary.
|
||||||
|
required: ['version']
|
||||||
|
# TODO: TravisR - Make this render
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: Internationalised Policy
|
||||||
|
description: |-
|
||||||
|
The policy information for the specified language.
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: The translated name of the policy.
|
||||||
|
url:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The URL, which should include the policy ID, version, and language
|
||||||
|
in it, to be presented to the user as the policy. URLs should have
|
||||||
|
all three criteria to avoid conflicts when the policy is updated
|
||||||
|
in the future: for example, if this was "https://example.org/terms.html"
|
||||||
|
then the server would be unable to update it because the client would
|
||||||
|
have already added that URL to the ``m.accepted_terms`` collection.
|
||||||
|
required: ['name', 'url']
|
||||||
|
required: ['policies']
|
||||||
|
post:
|
||||||
|
summary: Indicates acceptance of terms to the server.
|
||||||
|
description: |-
|
||||||
|
Called by a client to indicate that the user has accepted/agreed to the included
|
||||||
|
set of URLs. Servers MUST NOT assume that the client will be sending all previously
|
||||||
|
accepted URLs and should therefore append the provided URLs to what the server
|
||||||
|
already knows has been accepted.
|
||||||
|
|
||||||
|
Clients MUST provide the URL of the policy in the language that was presented
|
||||||
|
to the user. Servers SHOULD consider acceptance of any one language's URL as
|
||||||
|
acceptance for all other languages of that policy.
|
||||||
|
|
||||||
|
The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client
|
||||||
|
may not be accepting all terms at once.
|
||||||
|
operationId: agreeToTerms
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
user_accepts:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: The URLs the user is accepting in this request.
|
||||||
|
example: "https://example.org/somewhere/terms-2.0-en.html"
|
||||||
|
required: ['user_accepts']
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The server has considered the user as having accepted the provided URLs.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
@ -0,0 +1,53 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
title: Persistent Data Unit
|
||||||
|
description: A persistent data unit (event) for room version 4 and beyond.
|
||||||
|
example:
|
||||||
|
$ref: "../examples/pdu_v4.json"
|
||||||
|
allOf:
|
||||||
|
- $ref: "pdu_v3.yaml"
|
||||||
|
- type: object
|
||||||
|
properties:
|
||||||
|
redacts:
|
||||||
|
type: string
|
||||||
|
description: For redaction events, the ID of the event being redacted.
|
||||||
|
example: "$def_456-oldevent"
|
||||||
|
auth_events:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: Event ID.
|
||||||
|
description: |-
|
||||||
|
Event IDs for the authorization events that would
|
||||||
|
allow this event to be in the room.
|
||||||
|
|
||||||
|
Must contain less than or equal to 10 events. Note that if the relevant
|
||||||
|
auth event selection rules are used, this restriction should never be
|
||||||
|
encountered.
|
||||||
|
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||||
|
prev_events:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: Event ID.
|
||||||
|
description: |-
|
||||||
|
Event IDs for the most recent events in the room
|
||||||
|
that the homeserver was aware of when it made this event.
|
||||||
|
|
||||||
|
Must contain less than or equal to 20 events.
|
||||||
|
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||||
|
required:
|
||||||
|
- auth_events
|
||||||
|
- prev_events
|
||||||
@ -0,0 +1,58 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 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.
|
||||||
|
type: object
|
||||||
|
title: Room State
|
||||||
|
description: The state for the room.
|
||||||
|
properties:
|
||||||
|
origin:
|
||||||
|
type: string
|
||||||
|
description: The resident server's DNS name.
|
||||||
|
auth_chain:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The auth chain for the entire current room state prior to the join event.
|
||||||
|
|
||||||
|
Note that events have a different format depending on the room version - check the
|
||||||
|
`room version specification`_ for precise event formats.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: PDU
|
||||||
|
description: |-
|
||||||
|
The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
|
||||||
|
on the room version - check the `room version specification`_ for precise event formats.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties: []
|
||||||
|
example:
|
||||||
|
$ref: "../examples/minimal_pdu.json"
|
||||||
|
state:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The resolved current room state prior to the join event.
|
||||||
|
|
||||||
|
The event format varies depending on the room version - check the `room version specification`_
|
||||||
|
for precise event formats.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: PDU
|
||||||
|
description: |-
|
||||||
|
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
|
||||||
|
on the room version - check the `room version specification`_ for precise event formats.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties: []
|
||||||
|
example:
|
||||||
|
$ref: "../examples/minimal_pdu.json"
|
||||||
|
required: ["auth_chain", "state", "origin"]
|
||||||
@ -0,0 +1,32 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "transaction.yaml"
|
||||||
|
properties:
|
||||||
|
pdus:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
A single PDU. Note that events have a different format depending on the room
|
||||||
|
version - check the `room version specification`_ for precise event formats.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: PDU
|
||||||
|
description: |-
|
||||||
|
The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
|
||||||
|
on the room version - check the `room version specification`_ for precise event formats.
|
||||||
|
properties: []
|
||||||
|
example:
|
||||||
|
$ref: "../examples/minimal_pdu.json"
|
||||||
|
required: ['origin', 'origin_server_ts', 'pdus']
|
||||||
@ -0,0 +1,33 @@
|
|||||||
|
# Copyright 2019 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.
|
||||||
|
type: object
|
||||||
|
allOf:
|
||||||
|
- $ref: "transaction.yaml"
|
||||||
|
properties:
|
||||||
|
pdus:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
List of persistent updates to rooms. Note that events have a different format
|
||||||
|
depending on the room version - check the `room version specification`_ for
|
||||||
|
precise event formats.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: PDU
|
||||||
|
description: |-
|
||||||
|
The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
|
||||||
|
on the room version - check the `room version specification`_ for precise event formats.
|
||||||
|
properties: []
|
||||||
|
example:
|
||||||
|
$ref: "../examples/minimal_pdu.json"
|
||||||
|
required: ['origin', 'origin_server_ts', 'pdus']
|
||||||
@ -0,0 +1,12 @@
|
|||||||
|
{
|
||||||
|
"$ref": "pdu_v3.json",
|
||||||
|
"auth_events": [
|
||||||
|
"$urlsafe_base64_encoded_eventid",
|
||||||
|
"$a-different-event-id"
|
||||||
|
],
|
||||||
|
"prev_events": [
|
||||||
|
"$urlsafe_base64_encoded_eventid",
|
||||||
|
"$a-different-event-id"
|
||||||
|
],
|
||||||
|
"redacts": "$some-old_event"
|
||||||
|
}
|
||||||
@ -0,0 +1,136 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
# Copyright 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.
|
||||||
|
|
||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Federation Join Room API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8448
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /_matrix/federation/v2
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
# Note: there is no v2 of make_join (yet)
|
||||||
|
"/send_join/{roomId}/{eventId}":
|
||||||
|
put:
|
||||||
|
summary: Submit a signed join event to a resident server
|
||||||
|
description: |-
|
||||||
|
.. Note::
|
||||||
|
This API is nearly identical to the v1 API with the
|
||||||
|
exception of the response format being fixed.
|
||||||
|
|
||||||
|
This endpoint is preferred over the v1 API as it provides
|
||||||
|
a more standarised response format. Senders which receive
|
||||||
|
a 400, 404, or other status code which indicates this endpoint
|
||||||
|
is not available should retry using the v1 API instead.
|
||||||
|
|
||||||
|
Submits a signed join event to the resident server for it
|
||||||
|
to accept it into the room's graph. Note that events have
|
||||||
|
a different format depending on the room version - check
|
||||||
|
the `room version specification`_ for precise event formats.
|
||||||
|
**The request and response body here describe the common
|
||||||
|
event fields in more detail and may be missing other required
|
||||||
|
fields for a PDU.**
|
||||||
|
operationId: sendJoinV2
|
||||||
|
security:
|
||||||
|
- signedRequest: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: roomId
|
||||||
|
type: string
|
||||||
|
description: The room ID that is about to be joined.
|
||||||
|
required: true
|
||||||
|
x-example: "!abc123:matrix.org"
|
||||||
|
- in: path
|
||||||
|
name: eventId
|
||||||
|
type: string
|
||||||
|
description: The event ID for the join event.
|
||||||
|
required: true
|
||||||
|
x-example: "$abc123:example.org"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
type: object
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
sender:
|
||||||
|
type: string
|
||||||
|
description: The user ID of the joining member.
|
||||||
|
example: "@someone:example.org"
|
||||||
|
origin:
|
||||||
|
type: string
|
||||||
|
description: The name of the joining homeserver.
|
||||||
|
example: "matrix.org"
|
||||||
|
origin_server_ts:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: A timestamp added by the joining homeserver.
|
||||||
|
example: 1234567890
|
||||||
|
type:
|
||||||
|
type: string
|
||||||
|
description: The value ``m.room.member``.
|
||||||
|
example: "m.room.member"
|
||||||
|
state_key:
|
||||||
|
type: string
|
||||||
|
description: The user ID of the joining member.
|
||||||
|
example: "@someone:example.org"
|
||||||
|
content:
|
||||||
|
type: object
|
||||||
|
title: Membership Event Content
|
||||||
|
description: The content of the event.
|
||||||
|
example: {"membership": "join"}
|
||||||
|
properties:
|
||||||
|
membership:
|
||||||
|
type: string
|
||||||
|
description: The value ``join``.
|
||||||
|
example: "join"
|
||||||
|
required: ['membership']
|
||||||
|
required:
|
||||||
|
- state_key
|
||||||
|
- sender
|
||||||
|
- origin
|
||||||
|
- origin_server_ts
|
||||||
|
- type
|
||||||
|
- content
|
||||||
|
example: {
|
||||||
|
"$ref": "examples/minimal_pdu.json",
|
||||||
|
"type": "m.room.member",
|
||||||
|
"state_key": "@someone:example.org",
|
||||||
|
"origin": "example.org",
|
||||||
|
"origin_server_ts": 1549041175876,
|
||||||
|
"sender": "@someone:example.org",
|
||||||
|
"content": {
|
||||||
|
"membership": "join"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: |-
|
||||||
|
The full state for the room, having accepted the join event.
|
||||||
|
schema:
|
||||||
|
$ref: "./definitions/send_join_response.yaml"
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"origin": "matrix.org",
|
||||||
|
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
|
||||||
|
"state": [{"$ref": "examples/minimal_pdu.json"}]
|
||||||
|
}
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue