archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into travis/msc/integrations/auth

Browse Source
pull/977/head
Travis Ralston 5 years ago
parent bfd8e52c23 ad5d46d331
commit a2a7b7ff13
180 changed files with 4448 additions and 1479 deletions
Show Stats Download Patch File Download Diff File

16
.buildkite/pipeline.yaml
Unescape Escape View File

@ -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"

34
CONTRIBUTING.rst
Unescape Escape View File

@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
server before they can be documented in the specification. This process can take
some time to complete.
For this reason, we have not found the github pull-request model effective for
discussing changes to the specification. Instead, we have adopted the workflow
as described at https://matrix.org/docs/spec/proposals - *please read this for
details on how to contribute spec changes*.
Changes to the protocol (new endpoints, ideas, etc) need to go through the
`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
If you're not sure, visit us at `#matrix-spec:matrix.org`_
and ask.
Other changes
@ -51,8 +52,7 @@ following:
<https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
(If there is any doubt about whether it is the spec or the implementations
that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_.)
that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
* Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility
@ -60,23 +60,23 @@ following:
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
label.
For example, recommendations for UI behaviour do not require a proposal
document. On the other hand, changes to event contents would be best
discussed in a proposal document even though no changes would be necessary to
server implementations.
For example, areas where the specification is unclear do not require a proposal
to fix. On the other hand, introducing new behaviour is best represented by a
proposal.
For such changes, please do just open a `pull request`_.
For such changes, please do just open a `pull request`_. If you're not sure if
your change is covered by the above, please visit `#matrix-spec:matrix.org` and
ask.
.. _pull request: https://help.github.com/articles/about-pull-requests
.. _`pull request`: https://help.github.com/articles/about-pull-requests
.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
Adding to the changelog
~~~~~~~~~~~~~~~~~~~~~~~
Currently only changes to the client-server API need to end up in a changelog. The
other APIs are not yet stable and therefore do not have a changelog. Adding to the
changelog can only be done after you've opened your pull request, so be sure to do
that first.
All API specifications require a changelog entry. Adding to the changelog can only
be done after you've opened your pull request, so be sure to do that first.
The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
form of "news fragments". The news fragments for the client-server API are stored
@ -96,7 +96,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
* ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something
* ``deprecation`` - Used when deprecating something.
All news fragments must have a brief summary explaining the change in the
contents of the file. The summary must end in a full stop to be in line with

2
api/application-service/transactions.yaml
Unescape Escape View File

@ -56,7 +56,7 @@ paths:
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
{"$ref": "../../event-schemas/examples/m.room.message$m.text"}
]
}
description: Transaction information

112
api/client-server/administrative_contact.yaml
Unescape Escape View File

@ -134,9 +134,27 @@ paths:
200:
description: The addition was successful.
examples:
application/json: {}
application/json: {
"submit_url": "https://example.org/path/to/submitToken"
}
schema:
type: object
properties:
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. 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"
403:
description: The credentials could not be verified with the identity server.
examples:
@ -163,6 +181,14 @@ paths:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
@ -180,41 +206,55 @@ paths:
user.
schema:
type: object
properties: {}
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. ``success`` indicates that the
indentity server has unbound the identifier whereas ``no-support``
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
tags:
- User data
"/account/3pid/email/requestToken":
post:
summary: Begins the validation process for an email address for association with the user's account.
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address is **not** already associated
with an account on this homeserver. This API should be used to request
validation tokens when adding an email address to an account. This API's
parameters and response are identical to that of the |/register/email/requestToken|_
endpoint.
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding an email address to an
account. This API's parameters and response are identical to that of
the |/register/email/requestToken|_ endpoint. The homeserver has the
choice of validating the email address itself, or proxying the request
to the ``/validate/email/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
description: |-
An email was sent to the given address. Note that this may be an
email containing the validation token or it may be informing the
user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -241,34 +281,28 @@ paths:
post:
summary: Begins the validation process for a phone number for association with the user's account.
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is **not** already associated
with an account on this homeserver. This API should be used to request
validation tokens when adding a phone number to an account. This API's
parameters and response are identical to that of the |/register/msisdn/requestToken|_
endpoint.
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding a phone number to an
account. This API's parameters and response are identical to that of
the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
choice of validating the phone number itself, or proxying the request
to the ``/validate/msisdn/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a

127
api/client-server/content-repo.yaml
Unescape Escape View File

@ -1,4 +1,5 @@
# 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.
@ -41,7 +42,7 @@ paths:
name: Content-Type
type: string
description: The content type of the file being uploaded
x-example: "Content-Type: audio/mpeg"
x-example: "Content-Type: application/pdf"
- in: query
type: string
x-example: "War and Peace.pdf"
@ -51,24 +52,48 @@ paths:
name: "<content>"
description: The content to be uploaded.
required: true
x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
schema:
type: string
example: "<bytes>"
format: byte
responses:
200:
description: The MXC URI for the uploaded content.
description: The `MXC URI`_ for the uploaded content.
schema:
type: object
required: ["content_uri"]
properties:
content_uri:
type: string
description: "The MXC URI to the uploaded content."
description: "The `MXC URI`_ to the uploaded content."
examples:
application/json: {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
403:
description: |-
The user does not have permission to upload the content. Some reasons for this error include:
- The server does not permit the file type.
- The user has reached a quota for uploaded content.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot upload this content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The uploaded content is too large for the server.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Cannot upload files larger than 100mb"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -113,10 +138,23 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of the file that was previously uploaded, if set."
description: |-
The name of the file that was previously uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -125,7 +163,9 @@ paths:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: "Download content from the content repository as a given filename."
summary: |-
Download content from the content repository. This is the same as
the download endpoint above, except permitting a desired file name.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
@ -148,8 +188,7 @@ paths:
name: fileName
x-example: filename.jpg
required: true
description: |
The filename to give in the Content-Disposition
description: A filename to give in the ``Content-Disposition`` header.
- in: query
type: boolean
name: allow_remote
@ -168,10 +207,24 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of file given in the request"
description: |-
The ``fileName`` requested or the name of the file that was previously
uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -180,7 +233,9 @@ paths:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
summary: |-
Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
section for more information.
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
@ -188,7 +243,7 @@ paths:
type: string
name: serverName
required: true
x-example: matrix.org
x-example: example.org
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
@ -202,22 +257,26 @@ paths:
type: integer
x-example: 64
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* width of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: integer
x-example: 64
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* height of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: string
enum: ["crop", "scale"]
name: method
x-example: "scale"
description: The desired resizing method.
description: |-
The desired resizing method. See the `thumbnailing <#thumbnails>`_
section for more information.
- in: query
type: boolean
name: allow_remote
@ -238,6 +297,40 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
400:
description: |-
The request does not make sense to the server, or the server cannot thumbnail
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Cannot generate thumbnails for the requested content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The local content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
502:
description: |-
The remote content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -256,7 +349,7 @@ paths:
type: string
x-example: "https://matrix.org"
name: url
description: "The URL to get a preview of"
description: "The URL to get a preview of."
required: true
- in: query
type: integer
@ -284,7 +377,7 @@ paths:
"og:image":
type: string
description: |-
An MXC URI to the image. Omitted if there is no image.
An `MXC URI`_ to the image. Omitted if there is no image.
examples:
application/json: {
"og:title": "Matrix Blog Post",

12
api/client-server/definitions/push_condition.yaml
Unescape Escape View File

@ -16,16 +16,20 @@ title: PushCondition
type: object
properties:
kind:
enum:
- event_match
- contains_display_name
- room_member_count
type: string
description: |-
The kind of condition to apply. See `conditions <#conditions>`_ for
more information on the allowed kinds and how they work.
key:
type: string
description: |-
Required for ``event_match`` conditions. The dot-separated field of the
event to match.
Required for ``sender_notification_permission`` conditions. The field in
the power level event the user needs a minimum power level for. Fields
must be specified under the ``notifications`` property in the power level
event's ``content``.
x-example: content.body
pattern:
type: string

26
api/client-server/definitions/request_email_validation.yaml
Unescape Escape View File

@ -0,0 +1,26 @@
# 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.
example: "id.example.com"
required: ["id_server"]

26
api/client-server/definitions/request_msisdn_validation.yaml
Unescape Escape View File

@ -0,0 +1,26 @@
# 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.
example: "id.example.com"
required: ["id_server"]

37
api/client-server/definitions/request_token_response.yaml
Unescape Escape View File

@ -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. 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']

14
api/client-server/definitions/room_event_filter.yaml
Unescape Escape View File

@ -16,6 +16,20 @@ allOf:
- type: object
title: RoomEventFilter
properties:
lazy_load_members:
type: boolean
description: |-
If ``true``, enables lazy-loading of membership events. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
include_redundant_members:
type: boolean
description: |-
If ``true``, sends all membership events for all events, even if they have already
been sent to the client. Does not
apply unless ``lazy_load_members`` is ``true``. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``

27
api/client-server/definitions/sync_filter.yaml
Unescape Escape View File

@ -73,33 +73,6 @@ properties:
allOf:
- $ref: room_event_filter.yaml
description: The state events to include for rooms.
properties:
lazy_load_members:
type: boolean
description: |-
If ``true``, the only ``m.room.member`` events returned in
the ``state`` section of the ``/sync`` response are those
which are definitely necessary for a client to display
the ``sender`` of the timeline events in that response.
If ``false``, ``m.room.member`` events are not filtered.
By default, servers should suppress duplicate redundant
lazy-loaded ``m.room.member`` events from being sent to a given
client across multiple calls to ``/sync``, given that most clients
cache membership events (see ``include_redundant_members``
to change this behaviour).
include_redundant_members:
type: boolean
description: |-
If ``true``, the ``state`` section of the ``/sync`` response will
always contain the ``m.room.member`` events required to display
the ``sender`` of the timeline events in that response, assuming
``lazy_load_members`` is enabled. This means that redundant
duplicate member events may be returned across multiple calls to
``/sync``. This is useful for naive clients who never track
membership data. If ``false``, duplicate ``m.room.member`` events
may be suppressed by the server across multiple calls to ``/sync``.
If ``lazy_load_members`` is ``false`` this field is ignored.
timeline:
allOf:
- $ref: room_event_filter.yaml

41
api/client-server/definitions/third_party_signed.yaml
Unescape Escape View File

@ -0,0 +1,41 @@
# 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
example: {
"example.org": {
"ed25519:0": "some9signature"
}
}
required: ["sender", "mxid", "token", "signatures"]

9
api/client-server/directory.yaml
Unescape Escape View File

@ -148,5 +148,14 @@ paths:
}
schema:
type: object
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory

59
api/client-server/event_context.yaml
Unescape Escape View File

@ -34,6 +34,9 @@ paths:
This API returns a number of events that happened just before and
after the specified event. This allows clients to get the context
surrounding an event.
*Note*: This endpoint supports lazy-loading of room member events. See
`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
operationId: getEventContext
security:
- accessToken: []
@ -104,60 +107,30 @@ paths:
"end": "t29-57_2_0_2",
"events_after": [
{
"age": 91911336,
"content": {
"body": "7",
"msgtype": "m.text"
},
"event_id": "$14460306086CiUaL:localhost:8480",
"origin_server_ts": 1446030608551,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"event": {
"event_id": "$f3h4d129462ha:example.com",
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.image"
},
"events_before": [
{
"age": 91911903,
"content": {
"body": "5",
"msgtype": "m.text"
},
"event_id": "$14460306074UYTlh:localhost:8480",
"origin_server_ts": 1446030607984,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"age": 3123715284,
"content": {
"creator": "@test:localhost:8480"
},
"event_id": "$14429988040dgQAE:localhost:8480",
"origin_server_ts": 1442998804603,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "",
"type": "m.room.create",
"sender": "@test:localhost:8480"
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 2067105053,
"content": {
"avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
"displayname": "Bob2",
"membership": "join"
},
"event_id": "$14440554144URDbf:localhost:8480",
"origin_server_ts": 1444055414834,
"replaces_state": "$14440552472PgiGk:localhost:8480",
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "@test:localhost:8480",
"type": "m.room.member",
"sender": "@test:localhost:8480"
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}

69
api/client-server/joining.yaml
Unescape Escape View File

@ -58,38 +58,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
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.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-
@ -163,45 +134,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
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:
signed:
type: object
title: Signed
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
required: ["signed"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-

96
api/client-server/keys.yaml
Unescape Escape View File

@ -56,25 +56,48 @@ paths:
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
``<algorithm>:<key_id>``. The format of the key is determined
by the key algorithm.
by the `key algorithm <#key-algorithms>`_.
May be absent if no new one-time keys are required.
additionalProperties:
type:
- string
- object
example:
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8"
signed_curve25519:AAAAHg:
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
signed_curve25519:AAAAHQ:
key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
# - type: object
# title: KeyObject
# properties:
# key:
# type: string
# description: The key, encoded using unpadded base64.
# signatures:
# type: object
# description: |-
# Signature for the device. Mapped from user ID to signature object.
# additionalProperties:
# type: string
# required: ['key', 'signatures']
example: {
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
},
"signed_curve25519:AAAAHQ": {
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
}
}
responses:
200:
description:
@ -246,14 +269,15 @@ paths:
type: string
description: algorithm
example: "signed_curve25519"
example:
example: {
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
}
required:
- one_time_keys
responses:
200:
description:
The claimed keys
The claimed keys.
schema:
type: object
properties:
@ -275,20 +299,46 @@ paths:
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the `key algorithms <#key-algorithms>`_ section for information
on the Key Object format.
additionalProperties:
type: object
additionalProperties:
type:
- string
- object
example:
"@alice:example.com":
JLAFKJWSCS:
signed_curve25519:AAAAHg:
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
# - type: object
# title: KeyObject
# properties:
# key:
# type: string
# description: The key, encoded using unpadded base64.
# signatures:
# type: object
# description: |-
# Signature for the device. Mapped from user ID to signature object.
# additionalProperties:
# type: string
# required: ['key', 'signatures']
example: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
}
required: ['one_time_keys']
tags:
- End-to-end encryption
"/keys/changes":

7
api/client-server/logout.yaml
Unescape Escape View File

@ -32,7 +32,8 @@ paths:
summary: Invalidates a user access token
description: |-
Invalidates an existing access token, so that it can no longer be used for
authorization.
authorization. The device associated with the access token is also deleted.
`Device keys <#device-keys>`_ for the device are deleted alongside the device.
operationId: logout
security:
- accessToken: []
@ -49,7 +50,9 @@ paths:
summary: Invalidates all access tokens for a user
description: |-
Invalidates all access tokens for a user, so that they can no longer be used for
authorization. This includes the access token that made this request.
authorization. This includes the access token that made this request. All devices
for the user are also deleted. `Device keys <#device-keys>`_ for the device are
deleted alongside the device.
This endpoint does not require UI authorization because UI authorization is
designed to protect against attacks where the someone gets hold of a single access

62
api/client-server/message_pagination.yaml
Unescape Escape View File

@ -33,6 +33,9 @@ paths:
description: |-
This API returns a list of message and state events for a room. It uses
pagination query parameters to paginate history in the room.
*Note*: This endpoint supports lazy-loading of room member events. See
`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
operationId: getRoomEvents
security:
- accessToken: []
@ -103,54 +106,45 @@ paths:
chunk:
type: array
description: |-
A list of room events.
A list of room events. The order depends on the ``dir`` parameter.
For ``dir=b`` events will be in reverse-chronological order,
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: array
description: |-
A list of state events relevant to showing the ``chunk``. For example, if
``lazy_load_members`` is enabled in the filter then this may contain
the membership events for the senders of events in the ``chunk``.
Unless ``include_redundant_members`` is ``true``, the server
may remove membership events which would have already been
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
type: object
title: RoomStateEvent
$ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"origin_server_ts": 1444812213737,
"sender": "@alice:example.com",
"event_id": "$1444812213350496Caaaa:example.com",
"content": {
"body": "hello world",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 1042
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"origin_server_ts": 1444812194656 ,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Cbbbb:example.com",
"content": {
"body": "the world is big",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 20123
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.name"
},
{
"origin_server_ts": 1444812163990,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Ccccc:example.com",
"content": {
"name": "New room name"
},
"prev_content": {
"name": "Old room name"
},
"state_key": "",
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.name",
"age": 50789
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
]
}

11
api/client-server/notifications.yaml
Unescape Escape View File

@ -75,16 +75,7 @@ paths:
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"sender": "@alice:example.com",
"type": "m.room.message",
"age": 124524,
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

124
api/client-server/old_sync.yaml
Unescape Escape View File

@ -64,18 +64,7 @@ paths:
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
}
{"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
]
}
schema:
@ -142,16 +131,7 @@ paths:
application/json: {
"end": "s3456_9_0",
"presence": [
{
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"last_active_ago": 31053,
"presence": "online",
"user_id": "@bob:localhost"
},
"type": "m.presence"
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
],
"account_data": [
{
@ -167,28 +147,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@alice:localhost"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:localhost",
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
],
"end": "s3456_9_0",
@ -197,81 +161,20 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:localhost",
"origin_server_ts": 1425999732392,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:localhost"
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:localhost",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member",
"sender": "@alice:localhost"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:localhost"
},
"event_id": "$14259997320KhbwJ:localhost",
"origin_server_ts": 1425999732089,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:localhost"
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:localhost",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:localhost",
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member",
"sender": "@bob:localhost"
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:localhost": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:localhost",
"origin_server_ts": 1425999732285,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:localhost"
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",
@ -423,16 +326,7 @@ paths:
200:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
application/json: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
schema:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"

12
api/client-server/peeking_events.yaml
Unescape Escape View File

@ -75,16 +75,8 @@ paths:
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"room_id": "!somewhere:over.the.rainbow",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
]
}

218
api/client-server/registration.yaml
Unescape Escape View File

@ -29,7 +29,8 @@ paths:
post:
summary: Register for an account on this homeserver.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_, except in
the cases where a guest account is being registered.
Register for an account on this homeserver.
@ -59,6 +60,14 @@ paths:
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
When registering a guest account, all parameters in the request body
with the exception of ``initial_device_display_name`` MUST BE ignored
by the server. The server MUST pick a ``device_id`` for the account
regardless of input.
Any user ID returned by this API must conform to the grammar given in the
`Matrix specification <../appendices.html#user-identifiers>`_.
operationId: register
parameters:
- in: query
@ -72,7 +81,7 @@ paths:
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
description: The kind of account to register. Defaults to ``user``.
- in: body
name: body
schema:
@ -84,9 +93,7 @@ paths:
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself. It should be
left empty, or omitted, unless an earlier call returned an
response with status code 401.
authenticate the ``register`` call itself.
"$ref": "definitions/auth_data.yaml"
bind_email:
type: boolean
@ -94,6 +101,12 @@ paths:
If true, the server binds the email used for authentication to
the Matrix ID with the identity server.
example: false
bind_msisdn:
type: boolean
description: |-
If true, the server binds the phone number used for authentication
to the Matrix ID with the identity server.
example: false
username:
type: string
description: |-
@ -142,7 +155,7 @@ paths:
The fully-qualified Matrix user ID (MXID) that has been registered.
Any user ID returned by this API must conform to the grammar given in the
`Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.
`Matrix specification <../appendices.html#user-identifiers>`_.
access_token:
type: string
description: |-
@ -194,6 +207,18 @@ paths:
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular ``kind`` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -204,35 +229,28 @@ paths:
post:
summary: Begins the validation process for an email to be used during registration.
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address is not already associated
with an account on this homeserver. See the Identity Service API for
further information.
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the email address itself, or proxying the
request to the ``/validate/email/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: |-
An email has been sent to the specified address.
Note that this may be an email containing the validation token or it may be informing
the user of an error.
An email has been sent to the specified address. Note that this
may be an email containing the validation token or it may be
informing the user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
@ -264,35 +282,28 @@ paths:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is not already associated
with an account on this homeserver. See the Identity Service API for
further information.
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the phone number itself, or proxying the
request to the ``/validate/msisdn/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_msisdn_validation.yaml"
responses:
200:
description: |-
An SMS message has been sent to the specified phone number.
Note that this may be an SMS message containing the validation token or it may be informing
the user of an error.
An SMS message has been sent to the specified phone number. Note
that this may be an SMS message containing the validation token or
it may be informing the user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
@ -326,13 +337,17 @@ paths:
description: |-
Changes the password for an account on this homeserver.
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_ to
ensure the user changing the password is actually the owner of the
account.
An access token should be submitted to this endpoint if the client has
an active session.
The homeserver may change the flows available depending on whether a
valid access token is provided.
valid access token is provided. The homeserver SHOULD NOT revoke the
access token provided in the request, however all other access tokens
for the user should be revoked if the request succeeds.
security:
- accessToken: []
operationId: changePassword
@ -373,16 +388,25 @@ paths:
post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address **is** associated with an account
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/email/requestToken|_ except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
This API's parameters and response are identical to that of the
|/register/email/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
given email address could be found. The server may instead send an
email to the given address prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the email address itself,
or proxying the request to the ``/validate/email/requestToken``
Identity Service API. The request should be proxied to the domain that
is sent by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
@ -393,22 +417,12 @@ paths:
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -435,16 +449,24 @@ paths:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number **is** associated with an account
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/msisdn/requestToken|_ except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given phone number could be found. The server may instead send an
SMS message to the given address prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
This API's parameters and response are identical to that of the
|/register/msisdn/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
given phone number could be found. The server may instead send the SMS
to the given phone number prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the phone number itself, or
proxying the request to the ``/validate/msisdn/requestToken`` Identity
Service API. The request should be proxied to the domain that is sent
by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
@ -455,22 +477,12 @@ paths:
name: body
required: true
schema:
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.
example: "id.example.com"
required: ['id_server']
$ref: "../identity/definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -520,13 +532,39 @@ paths:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the ``id_server``
that was originally use to bind each identifier. If the
homeserver does not know which ``id_server`` that was,
it must return an ``id_server_unbind_result`` of
``no-support``.
example: "example.org"
responses:
200:
description: The account has been deactivated.
examples:
application/json: {}
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "success"
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). ``success`` indicates
that all identifiers have been unbound from the identity server while
``no-support`` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be ``success`` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.

89
api/client-server/room_initial_sync.yaml
Unescape Escape View File

@ -43,28 +43,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:example.com",
"origin_server_ts": 1432804485886,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:example.com",
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"end": "s3456_9_0",
@ -73,81 +57,20 @@ paths:
"room_id": "!636q39766251:example.com",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",

74
api/client-server/room_state.yaml
Unescape Escape View File

@ -31,6 +31,9 @@ paths:
put:
summary: Send a state event to the given room.
description: |
.. For backwards compatibility with older links...
.. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match.
@ -61,7 +64,9 @@ paths:
- in: path
type: string
name: stateKey
description: The state_key for the state to send. Defaults to the empty string.
description: |-
The state_key for the state to send. Defaults to the empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: "@alice:example.com"
- in: body
@ -70,7 +75,7 @@ paths:
type: object
example: {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
responses:
@ -99,68 +104,3 @@ paths:
}
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
put:
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. This endpoint is
equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
with an empty `stateKey`. Previous state events with matching
`<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
``state_key``. Furthermore, ``POST`` is unsupported on state paths.
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
operationId: setRoomState
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.name"
- in: body
name: body
schema:
type: object
example: {
"name": "New name for the room"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation

195
api/client-server/rooms.yaml
Unescape Escape View File

@ -42,7 +42,7 @@ paths:
name: roomId
description: The ID of the room the event is in.
required: true
x-example: "!asfDuShaf7Gafaw:matrix.org"
x-example: "!636q39766251:matrix.org"
- in: path
type: string
name: eventId
@ -54,14 +54,8 @@ paths:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
"room_id": "!636q39766251:matrix.org",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
schema:
allOf:
@ -74,6 +68,9 @@ paths:
get:
summary: Get the state identified by the type and key.
description: |-
.. For backwards compatibility with older links...
.. _`get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
Looks up the contents of a state event in a room. If the user is
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
@ -97,51 +94,11 @@ paths:
- in: path
type: string
name: stateKey
description: The key of the state to look up.
required: true
x-example: ""
responses:
200:
description: The content of the state event.
examples:
application/json: {
"name": "Example room name"}
schema:
type: object
404:
description: The room has no state with the given type or key.
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
get:
summary: Get the state identified by the type, with the empty state key.
description: |-
Looks up the contents of a state event in a room. If the user is
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
taken from the state of the room when they left.
This looks up the state event with the empty state key.
operationId: getRoomStateByType
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to look up the state in.
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of state to look up.
The key of the state to look up. Defaults to an empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: "m.room.name"
x-example: ""
responses:
200:
description: The content of the state event.
@ -179,81 +136,20 @@ paths:
examples:
application/json: [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
]
schema:
@ -288,6 +184,44 @@ paths:
description: The room to get the member events for.
required: true
x-example: "!636q39766251:example.com"
- in: query
name: at
type: string
description: |-
The point in time (pagination token) to return members for in the room.
This token can be obtained from a ``prev_batch`` token returned for
each room by the sync API. Defaults to the current state of the room,
as determined by the server.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
# XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
# filter might be a better alternative.
# See https://github.com/matrix-org/matrix-doc/issues/1337
- in: query
name: membership
type: string
enum:
- join
- invite
- leave
- ban
description: |-
The kind of membership to filter for. Defaults to no filtering if
unspecified. When specified alongside ``not_membership``, the two
parameters create an 'or' condition: either the membership *is*
the same as ``membership`` **or** *is not* the same as ``not_membership``.
x-example: "join"
- in: query
name: not_membership
type: string
enum:
- join
- invite
- leave
- ban
description: |-
The kind of membership to exclude from the results. Defaults to no
filtering if unspecified.
x-example: leave
security:
- accessToken: []
responses:
@ -300,33 +234,8 @@ paths:
application/json: {
"chunk": [
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}

11
api/client-server/search.yaml
Unescape Escape View File

@ -347,16 +347,9 @@ paths:
{
"rank": 0.00424866,
"result": {
"age": 526228296,
"content": {
"body": "Test content martians and men",
"msgtype": "m.text"
},
"event_id": "$144429830826TWwbB:localhost",
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"sender": "@test:localhost"
"event_id": "$144429830826TWwbB:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

143
api/client-server/sync.yaml
Unescape Escape View File

@ -34,6 +34,20 @@ paths:
Clients use this API when they first log in to get an initial snapshot
of the state on the server, and then continue to call this API to get
incremental deltas to the state, and to receive new messages.
*Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_
for more information. Lazy-loading members is only supported on a ``StateFilter``
for this endpoint. When lazy-loading is enabled, servers MUST include the
syncing user's own membership event when they join a room, or when the
full state of rooms is requested, to aid discovering the user's avatar &
displayname.
Like other members, the user's own membership event is eligible
for being considered redundant by the server. When a sync is ``limited``,
the server MUST return membership events for events in the gap
(between ``since`` and the start of the returned timeline), regardless
as to whether or not they are redundant. This ensures that joins/leaves
and profile changes which occur during the gap are not lost.
operationId: sync
security:
- accessToken: []
@ -49,6 +63,8 @@ paths:
requests. Creating a filter using the filter API is recommended for
clients that reuse the same filter multiple times, for example in
long poll requests.
See `Filtering <#filtering>`_ for more information.
x-example: "66696p746572"
- in: query
name: since
@ -125,6 +141,50 @@ paths:
title: Joined Room
type: object
properties:
summary:
title: RoomSummary
type: object
description: |-
Information about the room which clients may need to
correctly render it to users.
properties:
"m.heroes":
type: array
description: |-
The users which can be used to generate a room name
if the room does not have one. Required if the room's
``m.room.name`` or ``m.room.canonical_alias`` state events
are unset or empty.
This should be the first 5 members of the room, ordered
by stream ordering, which are joined or invited. The
list must never include the client's own user ID. When
no joined or invited members are available, this should
consist of the banned and left users. More than 5 members
may be provided, however less than 5 should only be provided
when there are less than 5 members to represent.
When lazy-loading room members is enabled, the membership
events for the heroes MUST be included in the ``state``,
unless they are redundant. When the list of users changes,
the server notifies the client by sending a fresh list of
heroes. If there are no changes since the last sync, this
field may be omitted.
items:
type: string
"m.joined_member_count":
type: integer
description: |-
The number of users with ``membership`` of ``join``,
including the client's own user ID. If this field has
not changed since the last sync, it may be omitted.
Required otherwise.
"m.invited_member_count":
type: integer
description: |-
The number of users with ``membership`` of ``invite``.
If this field has not changed since the last sync, it
may be omitted. Required otherwise.
state:
title: State
type: object
@ -167,11 +227,13 @@ paths:
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
"unread_notifications":
unread_notifications:
title: Unread Notification Counts
type: object
description: |-
Counts of unread notifications for this room
Counts of unread notifications for this room. See the
`Receiving notifications section <#receiving-notifications>`_
for more information on how these are calculated.
properties:
highlight_count:
title: Highlighted notification count
@ -212,30 +274,7 @@ paths:
events:
description: The StrippedState events that form the invite state.
items:
description: |-
A stripped down state event, with only the ``type``, ``state_key``,
``sender``, and ``content`` keys.
properties:
content:
description: The ``content`` for the event.
title: EventContent
type: object
state_key:
description: The ``state_key`` for the event.
type: string
type:
description: The ``type`` for the event.
type: string
sender:
description: The ``sender`` for the event.
type: string
required:
- type
- state_key
- content
- sender
title: StrippedState
type: object
$ref: "definitions/event-schemas/schema/stripped_state.yaml"
type: array
leave:
title: Left rooms
@ -310,11 +349,7 @@ paths:
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.presence",
"content": {"presence": "online"}
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
]
},
"account_data": {
@ -330,39 +365,31 @@ paths:
"rooms": {
"join": {
"!726s6s6q:example.com": {
"summary": {
"m.heroes": [
"@alice:example.com",
"@bob:example.com"
],
"m.joined_member_count": 2,
"m.invited_member_count": 0
},
"state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@alice:example.com",
"content": {"membership": "join"},
"origin_server_ts": 1417731086795,
"event_id": "$66697273743031:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
},
"timeline": {
"events": [
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "join"},
"prev_content": {"membership": "invite"},
"origin_server_ts": 1417731086795,
"event_id": "$7365636s6r6432:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"sender": "@alice:example.com",
"type": "m.room.message",
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"limited": true,
@ -370,18 +397,12 @@ paths:
},
"ephemeral": {
"events": [
{
"type": "m.typing",
"content": {"user_ids": ["@alice:example.com"]}
}
{"$ref": "definitions/event-schemas/examples/m.typing"}
]
},
"account_data": {
"events": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
},
{"$ref": "definitions/event-schemas/examples/m.tag"},
{
"type": "org.example.custom.room.config",
"content": {

98
api/identity/associations.yaml
Unescape Escape View File

@ -90,7 +90,7 @@ paths:
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/bind":
"/3pid/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
@ -201,3 +201,99 @@ paths:
}
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: unbind
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).
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.

8
api/identity/definitions/request_email_validation.yaml
Unescape Escape View File

@ -39,12 +39,14 @@ properties:
avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity server.
The client should increment this value if they desire a new
email (e.g. a reminder) to be sent.
email (e.g. a reminder) to be sent. If they do not, the server
should respond with success but not resend the email.
example: 1
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
server will redirect the user to this URL.
Optional. When the validation is completed, the identity server will
redirect the user to this URL. This option is ignored when submitting
3PID validation information through a POST request.
example: "https://example.org/congratulations.html"
required: ["client_secret", "email", "send_attempt"]

5
api/identity/definitions/request_msisdn_validation.yaml
Unescape Escape View File

@ -51,7 +51,8 @@ properties:
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
server will redirect the user to this URL.
Optional. When the validation is completed, the identity server will
redirect the user to this URL. This option is ignored when submitting
3PID validation information through a POST request.
example: "https://example.org/congratulations.html"
required: ["client_secret", "country", "phone_number", "send_attempt"]

47
api/identity/store_invite.yaml
Unescape Escape View File

@ -50,31 +50,66 @@ paths:
requests to ``/_matrix/identity/api/v1/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: storeInvite
parameters:
- in: body
name: body
schema:
type: object
example: {
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
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:

2
api/server-server/backfill.yaml
Unescape Escape View File

@ -64,7 +64,7 @@ paths:
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing

10
api/server-server/definitions/keys.yaml
Unescape Escape View File

@ -94,6 +94,12 @@ properties:
type: integer
format: int64
description: |-
POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
timestamp are no longer valid.
POSIX timestamp when the list of valid keys should be refreshed. This field MUST
be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST
be considered invalid, depending on the `room version specification`_.
Servers MUST use the lesser of this field and 7 days into the future when
determining if a key is valid. This is to avoid a situation where an attacker
publishes a key which is valid for a significant amount of time without a way
for the homeserver owner to revoke it.
example: 1052262000000

4
api/server-server/definitions/pdu_v3.yaml
Unescape Escape View File

@ -20,6 +20,10 @@ allOf:
- $ref: "unsigned_pdu_base.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:

47
api/server-server/definitions/pdu_v4.yaml
Unescape Escape View File

@ -0,0 +1,47 @@
# 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.
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.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

32
api/server-server/definitions/single_pdu_transaction.yaml
Unescape Escape View File

@ -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']

33
api/server-server/definitions/unlimited_pdu_transaction.yaml
Unescape Escape View File

@ -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']

2
api/server-server/events.yaml
Unescape Escape View File

@ -156,4 +156,4 @@ paths:
200:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/single_pdu_transaction.yaml"

3
api/server-server/examples/pdu_v3.json
Unescape Escape View File

@ -15,5 +15,6 @@
"prev_events": [
"$base64encodedeventid",
"$adifferenteventid"
]
],
"redacts": "$some/old+event"
}

12
api/server-server/examples/pdu_v4.json
Unescape Escape View File

@ -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"
}

71
api/server-server/invites-v1.yaml
Unescape Escape View File

@ -82,35 +82,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
@ -118,26 +92,6 @@ paths:
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": {
"membership": "invite"
},
@ -180,25 +134,10 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": {
"membership": "invite"
},

69
api/server-server/invites-v2.yaml
Unescape Escape View File

@ -83,35 +83,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
required: ['room_version', 'event']
example: {
"room_version": "2",
@ -130,25 +104,7 @@ paths:
"ed25519:key_version": "SomeSignatureHere"
},
}
},
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
}
responses:
200:
@ -174,24 +130,9 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
]
},
"content": {
"membership": "invite"

2
api/server-server/keys_query.yaml
Unescape Escape View File

@ -46,6 +46,8 @@ paths:
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
look up.
When excluded, the trailing slash on this endpoint is optional.
required: false
x-example: "ed25519:abc123"
- in: query

2
api/server-server/keys_server.yaml
Unescape Escape View File

@ -51,6 +51,8 @@ paths:
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
look up.
When excluded, the trailing slash on this endpoint is optional.
required: false
x-example: "ed25519:abc123"
deprecated: true

1
api/server-server/leaving.yaml
Unescape Escape View File

@ -57,7 +57,6 @@ paths:
`room version specification`_ for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
schema:
schema:
type: object
properties:

2
api/server-server/query.yaml
Unescape Escape View File

@ -128,7 +128,7 @@ paths:
x-example: "@someone:example.org"
- in: query
name: field
type: enum
type: string
enum: ['displayname', 'avatar_url']
description: |-
The field to query. If specified, the server will only return the given field

1
api/server-server/user_devices.yaml
Unescape Escape View File

@ -42,7 +42,6 @@ paths:
description: |-
The user ID to retrieve devices for. Must be a user local to the
receiving homeserver.
required: true
x-example: "@alice:example.org"
responses:
200:

28
api/server-server/user_keys.yaml
Unescape Escape View File

@ -63,7 +63,7 @@ paths:
- one_time_keys
responses:
200:
description: The claimed keys
description: The claimed keys.
schema:
type: object
properties:
@ -72,19 +72,31 @@ paths:
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the Client-Server Key Algorithms section for more information on
the Key Object format.
additionalProperties:
type: object
additionalProperties:
type:
- string
- object
required: ['one_time_keys']
examples:
application/json: {
"one_time_keys": {
- type: object
title: KeyObject
properties:
key:
type: string
description: The key, encoded using unpadded base64.
signatures:
type: object
description: |-
Signature for the device. Mapped from user ID to signature object.
additionalProperties:
type: string
required: ['key', 'signatures']
example: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25518:AAAAHg": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
@ -95,7 +107,7 @@ paths:
}
}
}
}
required: ['one_time_keys']
"/user/keys/query":
post:
summary: Download device identity keys.

1
api/server-server/version.yaml
Unescape Escape View File

@ -27,6 +27,7 @@ paths:
get:
summary: Get the implementation name and version of this homeserver.
description: Get the implementation name and version of this homeserver.
operationId: getVersion
responses:
200:
description:

1
api/server-server/wellknown.yaml
Unescape Escape View File

@ -29,6 +29,7 @@ paths:
Gets information about the delegated server for server-server communication
between Matrix homeservers. Servers should follow 30x redirects, carefully
avoiding redirect loops, and use normal X.509 certificate validation.
operationId: getWellKnown
responses:
200:
description:

10
changelogs/application_service.rst
Unescape Escape View File

@ -1,3 +1,13 @@
r0.1.1
======
Spec Clarifications
-------------------
- Change examples to use example.org instead of a real domain. (`#1650 <https://github.com/matrix-org/matrix-doc/issues/1650>`_)
- Add missing definition for how appservices verify requests came from a homeserver. (`#2037 <https://github.com/matrix-org/matrix-doc/issues/2037>`_)
r0.1.0
======

82
changelogs/client_server.rst
Unescape Escape View File

@ -1,3 +1,85 @@
r0.5.0
======
Breaking Changes
----------------
- Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. (`#2101 <https://github.com/matrix-org/matrix-doc/issues/2101>`_)
Deprecations
------------
- Remove references to presence lists. (`#1817 <https://github.com/matrix-org/matrix-doc/issues/1817>`_)
New Endpoints
-------------
- ``GET /account_data`` routes. (`#1873 <https://github.com/matrix-org/matrix-doc/issues/1873>`_)
Backwards Compatible Changes
----------------------------
- Add megolm session export format. (`#1701 <https://github.com/matrix-org/matrix-doc/issues/1701>`_)
- Add support for advertising experimental features to clients. (`#1786 <https://github.com/matrix-org/matrix-doc/issues/1786>`_)
- Add a generic SSO login API. (`#1789 <https://github.com/matrix-org/matrix-doc/issues/1789>`_)
- Add a mechanism for servers to redirect clients to an alternative homeserver after logging in. (`#1790 <https://github.com/matrix-org/matrix-doc/issues/1790>`_)
- Add room version upgrades. (`#1791 <https://github.com/matrix-org/matrix-doc/issues/1791>`_, `#1875 <https://github.com/matrix-org/matrix-doc/issues/1875>`_)
- Support optional features by having clients query for capabilities. (`#1829 <https://github.com/matrix-org/matrix-doc/issues/1829>`_, `#1879 <https://github.com/matrix-org/matrix-doc/issues/1879>`_)
- Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them. (`#1874 <https://github.com/matrix-org/matrix-doc/issues/1874>`_)
- Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs. (`#1908 <https://github.com/matrix-org/matrix-doc/issues/1908>`_)
- Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications. (`#2020 <https://github.com/matrix-org/matrix-doc/issues/2020>`_)
- Add support for sending server notices to clients. (`#2026 <https://github.com/matrix-org/matrix-doc/issues/2026>`_)
- Add MSISDN (phone number) support to User-Interactive Authentication. (`#2030 <https://github.com/matrix-org/matrix-doc/issues/2030>`_)
- Add the option to lazy-load room members for increased client performance. (`#2035 <https://github.com/matrix-org/matrix-doc/issues/2035>`_)
- Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server. (`#2046 <https://github.com/matrix-org/matrix-doc/issues/2046>`_)
- Add support for Olm sessions becoming un-stuck. (`#2059 <https://github.com/matrix-org/matrix-doc/issues/2059>`_)
- Add interactive device verification, including a common framework for device verification. (`#2072 <https://github.com/matrix-org/matrix-doc/issues/2072>`_)
Spec Clarifications
-------------------
- Change examples to use example.org instead of a real domain. (`#1650 <https://github.com/matrix-org/matrix-doc/issues/1650>`_)
- Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50. (`#1656 <https://github.com/matrix-org/matrix-doc/issues/1656>`_)
- Add missing ``status_msg`` to ``m.presence`` schema. (`#1744 <https://github.com/matrix-org/matrix-doc/issues/1744>`_)
- Fix various spelling mistakes throughout the specification. (`#1838 <https://github.com/matrix-org/matrix-doc/issues/1838>`_, `#1853 <https://github.com/matrix-org/matrix-doc/issues/1853>`_, `#1860 <https://github.com/matrix-org/matrix-doc/issues/1860>`_, `#1933 <https://github.com/matrix-org/matrix-doc/issues/1933>`_, `#1969 <https://github.com/matrix-org/matrix-doc/issues/1969>`_, `#1988 <https://github.com/matrix-org/matrix-doc/issues/1988>`_, `#1989 <https://github.com/matrix-org/matrix-doc/issues/1989>`_, `#1991 <https://github.com/matrix-org/matrix-doc/issues/1991>`_, `#1992 <https://github.com/matrix-org/matrix-doc/issues/1992>`_)
- Add the missing ``m.push_rules`` event schema. (`#1889 <https://github.com/matrix-org/matrix-doc/issues/1889>`_)
- Clarify how modern day local echo is meant to be solved by clients. (`#1891 <https://github.com/matrix-org/matrix-doc/issues/1891>`_)
- Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. (`#1975 <https://github.com/matrix-org/matrix-doc/issues/1975>`_)
- Clarify how ``m.login.dummy`` can be used to disambiguate login flows. (`#1999 <https://github.com/matrix-org/matrix-doc/issues/1999>`_)
- Remove ``prev_content`` from the redaction algorithm's essential keys list. (`#2016 <https://github.com/matrix-org/matrix-doc/issues/2016>`_)
- Fix the ``third_party_signed`` definitions for the join APIs. (`#2025 <https://github.com/matrix-org/matrix-doc/issues/2025>`_)
- Clarify why User Interactive Auth is used on password changes and how access tokens are handled. (`#2027 <https://github.com/matrix-org/matrix-doc/issues/2027>`_)
- Clarify that devices are deleted upon logout. (`#2028 <https://github.com/matrix-org/matrix-doc/issues/2028>`_)
- Add ``M_NOT_FOUND`` error definition for deleting room aliases. (`#2029 <https://github.com/matrix-org/matrix-doc/issues/2029>`_)
- Add missing ``reason`` to ``m.call.hangup``. (`#2031 <https://github.com/matrix-org/matrix-doc/issues/2031>`_)
- Clarify how redactions affect room state. (`#2032 <https://github.com/matrix-org/matrix-doc/issues/2032>`_)
- Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. (`#2036 <https://github.com/matrix-org/matrix-doc/issues/2036>`_)
- Fix example ``Content-Type`` for ``/media/upload`` request. (`#2041 <https://github.com/matrix-org/matrix-doc/issues/2041>`_)
- Clarify that login flows are meant to be completed in order. (`#2042 <https://github.com/matrix-org/matrix-doc/issues/2042>`_)
- Clarify that clients should not send read receipts for their own messages. (`#2043 <https://github.com/matrix-org/matrix-doc/issues/2043>`_)
- Use consistent examples of events throughout the specification. (`#2051 <https://github.com/matrix-org/matrix-doc/issues/2051>`_)
- Clarify which push rule condition kinds exist. (`#2052 <https://github.com/matrix-org/matrix-doc/issues/2052>`_)
- Clarify the required fields on ``m.file`` (and similar) messages. (`#2053 <https://github.com/matrix-org/matrix-doc/issues/2053>`_)
- Clarify that User-Interactive Authentication stages cannot be attempted more than once. (`#2054 <https://github.com/matrix-org/matrix-doc/issues/2054>`_)
- Clarify which parameters apply in what scenarios on ``/register``. (`#2055 <https://github.com/matrix-org/matrix-doc/issues/2055>`_)
- Clarify how to interpret changes of ``membership`` over time. (`#2056 <https://github.com/matrix-org/matrix-doc/issues/2056>`_)
- Clarify exactly what invite_room_state consists of. (`#2067 <https://github.com/matrix-org/matrix-doc/issues/2067>`_)
- Clarify how the content repository works, and what it is used for. (`#2068 <https://github.com/matrix-org/matrix-doc/issues/2068>`_)
- Clarify the order events in chunk are returned in for ``/messages``. (`#2069 <https://github.com/matrix-org/matrix-doc/issues/2069>`_)
- Clarify the key object definition for the key management API. (`#2083 <https://github.com/matrix-org/matrix-doc/issues/2083>`_)
- Reorganize information about events into a common section. (`#2087 <https://github.com/matrix-org/matrix-doc/issues/2087>`_)
- De-duplicate ``/state/<event_type>`` endpoints, clarifying that the ``<state_key>`` is optional. (`#2088 <https://github.com/matrix-org/matrix-doc/issues/2088>`_)
- Clarify when and where CORS headers should be returned. (`#2089 <https://github.com/matrix-org/matrix-doc/issues/2089>`_)
- Clarify when authorization and rate-limiting are not applicable. (`#2090 <https://github.com/matrix-org/matrix-doc/issues/2090>`_)
- Clarify that ``/register`` must produce valid Matrix User IDs. (`#2091 <https://github.com/matrix-org/matrix-doc/issues/2091>`_)
- Clarify how ``unread_notifications`` is calculated. (`#2097 <https://github.com/matrix-org/matrix-doc/issues/2097>`_)
- Clarify what a "module" is and update feature profiles for clients. (`#2098 <https://github.com/matrix-org/matrix-doc/issues/2098>`_)
r0.4.0
======

1
changelogs/client_server/newsfragments/1701.feature
Unescape Escape View File

@ -1 +0,0 @@
Documented megolm session export format.

1
changelogs/client_server/newsfragments/1744.clarification
Unescape Escape View File

@ -1 +0,0 @@
Add missing status_msg to m.presence schema.

1
changelogs/client_server/newsfragments/1786.feature
Unescape Escape View File

@ -1 +0,0 @@
Add support for advertising experimental features to clients.

1
changelogs/client_server/newsfragments/1789.feature
Unescape Escape View File

@ -1 +0,0 @@
Add a generic SSO login API.

1
changelogs/client_server/newsfragments/1790.feature
Unescape Escape View File

@ -1 +0,0 @@
Add a mechanism for servers to redirect clients to an alternative homeserver after logging in.

1
changelogs/client_server/newsfragments/1791.feature
Unescape Escape View File

@ -1 +0,0 @@
Add room version upgrades.

1
changelogs/client_server/newsfragments/1817.deprecation
Unescape Escape View File

@ -1 +0,0 @@
Remove references to presence lists.

1
changelogs/client_server/newsfragments/1829.feature
Unescape Escape View File

@ -1 +0,0 @@
Support optional features by having clients query for capabilities.

1
changelogs/client_server/newsfragments/1838.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1853.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1860.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1873.new
Unescape Escape View File

@ -1 +0,0 @@
``GET /account_data`` routes.

1
changelogs/client_server/newsfragments/1874.feature
Unescape Escape View File

@ -1 +0,0 @@
Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them.

1
changelogs/client_server/newsfragments/1875.feature
Unescape Escape View File

@ -1 +0,0 @@
Add room version upgrades.

1
changelogs/client_server/newsfragments/1879.feature
Unescape Escape View File

@ -1 +0,0 @@
Support optional features by having clients query for capabilities.

1
changelogs/client_server/newsfragments/1889.clarification
Unescape Escape View File

@ -1 +0,0 @@
Add the missing `m.push_rules` event schema.

1
changelogs/client_server/newsfragments/1903.feature
Unescape Escape View File

@ -1 +0,0 @@
Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs.

1
changelogs/client_server/newsfragments/1933.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/2125.clarification
Unescape Escape View File

@ -0,0 +1 @@
Add missing format fields to ``m.room.message$m.notice`` schema.

1
changelogs/client_server/newsfragments/2129.clarification
Unescape Escape View File

@ -0,0 +1 @@
Remove "required" designation from the ``url`` field of certain ``m`.room.message` msgtypes.

1
changelogs/client_server/newsfragments/2131.clarification
Unescape Escape View File

@ -0,0 +1 @@
Fix typo in key verification framework section.

1
changelogs/client_server/newsfragments/2132.clarification
Unescape Escape View File

@ -0,0 +1 @@
Clarify the distinction between ``m.key.verification.start`` and its ``m.sas.v1`` variant.

1
changelogs/client_server/newsfragments/2133.clarification
Unescape Escape View File

@ -0,0 +1 @@
Fix link to Olm signing specification.

1
changelogs/client_server/newsfragments/2136.clarification
Unescape Escape View File

@ -0,0 +1 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/2148.misc
Unescape Escape View File

@ -0,0 +1 @@
Fix a small duplicated "as".

29
changelogs/identity_service.rst
Unescape Escape View File

@ -1,3 +1,32 @@
r0.2.1
======
Spec Clarifications
-------------------
- Remove incorrect ``id_server`` parameter from ``/requestToken`` endpoints. (`#2124 <https://github.com/matrix-org/matrix-doc/issues/2124>`_)
- Clarify that identity servers can return 403 for unbind requests. (`#2126 <https://github.com/matrix-org/matrix-doc/issues/2126>`_)
r0.2.0
======
New Endpoints
-------------
- Add ``/3pid/unbind`` for removing 3PIDs. (`#2046 <https://github.com/matrix-org/matrix-doc/issues/2046>`_)
Spec Clarifications
-------------------
- Fix various spelling mistakes throughout the specification. (`#1853 <https://github.com/matrix-org/matrix-doc/issues/1853>`_)
- Fix route for ``/3pid/bind``. (`#1967 <https://github.com/matrix-org/matrix-doc/issues/1967>`_)
- Add missing aesthetic parameters to ``/store-invite``. (`#2049 <https://github.com/matrix-org/matrix-doc/issues/2049>`_)
- Clarify what the client should receive upon sending an identical email validation request multiple times. (`#2057 <https://github.com/matrix-org/matrix-doc/issues/2057>`_)
- Clarify that the default transport is JSON over HTTP. (`#2086 <https://github.com/matrix-org/matrix-doc/issues/2086>`_)
r0.1.0
======

1
changelogs/identity_service/newsfragments/1853.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

17
changelogs/server_server.rst
Unescape Escape View File

@ -1,3 +1,20 @@
r0.1.2
======
Spec Clarifications
-------------------
- Change examples to use example.org instead of a real domain. (`#1650 <https://github.com/matrix-org/matrix-doc/issues/1650>`_)
- Fix the ``access_token`` parameter in the open_id endpoint. (`#1906 <https://github.com/matrix-org/matrix-doc/issues/1906>`_)
- Fix various spelling mistakes throughout the specification. (`#1991 <https://github.com/matrix-org/matrix-doc/issues/1991>`_)
- Clarify exactly what invite_room_state consists of. (`#2067 <https://github.com/matrix-org/matrix-doc/issues/2067>`_)
- Clarify how ``valid_until_ts`` behaves with respect to room version. (`#2080 <https://github.com/matrix-org/matrix-doc/issues/2080>`_)
- Clarify which servers are supposed to sign events. (`#2081 <https://github.com/matrix-org/matrix-doc/issues/2081>`_)
- Clarify the key object definition for the key management API. (`#2083 <https://github.com/matrix-org/matrix-doc/issues/2083>`_)
- Clarify how many PDUs are contained in transaction objects for various endpoints. (`#2095 <https://github.com/matrix-org/matrix-doc/issues/2095>`_)
- Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested. (`#2097 <https://github.com/matrix-org/matrix-doc/issues/2097>`_)
r0.1.1
======

1
changelogs/server_server/newsfragments/1904.clarification
Unescape Escape View File

@ -1 +0,0 @@
Fix the `access_token` parameter in the open_id endpoint.

66
data-definitions/sas-emoji.json
Unescape Escape View File

@ -0,0 +1,66 @@
[
{"number": 0, "emoji": "🐶", "description": "Dog", "unicode": "U+1F436"},
{"number": 1, "emoji": "🐱", "description": "Cat", "unicode": "U+1F431"},
{"number": 2, "emoji": "🦁", "description": "Lion", "unicode": "U+1F981"},
{"number": 3, "emoji": "🐎", "description": "Horse", "unicode": "U+1F40E"},
{"number": 4, "emoji": "🦄", "description": "Unicorn", "unicode": "U+1F984"},
{"number": 5, "emoji": "🐷", "description": "Pig", "unicode": "U+1F437"},
{"number": 6, "emoji": "🐘", "description": "Elephant", "unicode": "U+1F418"},
{"number": 7, "emoji": "🐰", "description": "Rabbit", "unicode": "U+1F430"},
{"number": 8, "emoji": "🐼", "description": "Panda", "unicode": "U+1F43C"},
{"number": 9, "emoji": "🐓", "description": "Rooster", "unicode": "U+1F413"},
{"number": 10, "emoji": "🐧", "description": "Penguin", "unicode": "U+1F427"},
{"number": 11, "emoji": "🐢", "description": "Turtle", "unicode": "U+1F422"},
{"number": 12, "emoji": "🐟", "description": "Fish", "unicode": "U+1F41F"},
{"number": 13, "emoji": "🐙", "description": "Octopus", "unicode": "U+1F419"},
{"number": 14, "emoji": "🦋", "description": "Butterfly", "unicode": "U+1F98B"},
{"number": 15, "emoji": "🌷", "description": "Flower", "unicode": "U+1F337"},
{"number": 16, "emoji": "🌳", "description": "Tree", "unicode": "U+1F333"},
{"number": 17, "emoji": "🌵", "description": "Cactus", "unicode": "U+1F335"},
{"number": 18, "emoji": "🍄", "description": "Mushroom", "unicode": "U+1F344"},
{"number": 19, "emoji": "🌏", "description": "Globe", "unicode": "U+1F30F"},
{"number": 20, "emoji": "🌙", "description": "Moon", "unicode": "U+1F319"},
{"number": 21, "emoji": "☁️", "description": "Cloud", "unicode": "U+2601U+FE0F"},
{"number": 22, "emoji": "🔥", "description": "Fire", "unicode": "U+1F525"},
{"number": 23, "emoji": "🍌", "description": "Banana", "unicode": "U+1F34C"},
{"number": 24, "emoji": "🍎", "description": "Apple", "unicode": "U+1F34E"},
{"number": 25, "emoji": "🍓", "description": "Strawberry", "unicode": "U+1F353"},
{"number": 26, "emoji": "🌽", "description": "Corn", "unicode": "U+1F33D"},
{"number": 27, "emoji": "🍕", "description": "Pizza", "unicode": "U+1F355"},
{"number": 28, "emoji": "🎂", "description": "Cake", "unicode": "U+1F382"},
{"number": 29, "emoji": "❤️", "description": "Heart", "unicode": "U+2764U+FE0F"},
{"number": 30, "emoji": "😀", "description": "Smiley", "unicode": "U+1F600"},
{"number": 31, "emoji": "🤖", "description": "Robot", "unicode": "U+1F916"},
{"number": 32, "emoji": "🎩", "description": "Hat", "unicode": "U+1F3A9"},
{"number": 33, "emoji": "👓", "description": "Glasses", "unicode": "U+1F453"},
{"number": 34, "emoji": "🔧", "description": "Spanner", "unicode": "U+1F527"},
{"number": 35, "emoji": "🎅", "description": "Santa", "unicode": "U+1F385"},
{"number": 36, "emoji": "👍", "description": "Thumbs Up", "unicode": "U+1F44D"},
{"number": 37, "emoji": "☂️", "description": "Umbrella", "unicode": "U+2602U+FE0F"},
{"number": 38, "emoji": "⌛", "description": "Hourglass", "unicode": "U+231B"},
{"number": 39, "emoji": "⏰", "description": "Clock", "unicode": "U+23F0"},
{"number": 40, "emoji": "🎁", "description": "Gift", "unicode": "U+1F381"},
{"number": 41, "emoji": "💡", "description": "Light Bulb", "unicode": "U+1F4A1"},
{"number": 42, "emoji": "📕", "description": "Book", "unicode": "U+1F4D5"},
{"number": 43, "emoji": "✏️", "description": "Pencil", "unicode": "U+270FU+FE0F"},
{"number": 44, "emoji": "📎", "description": "Paperclip", "unicode": "U+1F4CE"},
{"number": 45, "emoji": "✂️", "description": "Scissors", "unicode": "U+2702U+FE0F"},
{"number": 46, "emoji": "🔒", "description": "Lock", "unicode": "U+1F512"},
{"number": 47, "emoji": "🔑", "description": "Key", "unicode": "U+1F511"},
{"number": 48, "emoji": "🔨", "description": "Hammer", "unicode": "U+1F528"},
{"number": 49, "emoji": "☎️", "description": "Telephone", "unicode": "U+260EU+FE0F"},
{"number": 50, "emoji": "🏁", "description": "Flag", "unicode": "U+1F3C1"},
{"number": 51, "emoji": "🚂", "description": "Train", "unicode": "U+1F682"},
{"number": 52, "emoji": "🚲", "description": "Bicycle", "unicode": "U+1F6B2"},
{"number": 53, "emoji": "✈️", "description": "Aeroplane", "unicode": "U+2708U+FE0F"},
{"number": 54, "emoji": "🚀", "description": "Rocket", "unicode": "U+1F680"},
{"number": 55, "emoji": "🏆", "description": "Trophy", "unicode": "U+1F3C6"},
{"number": 56, "emoji": "⚽", "description": "Ball", "unicode": "U+26BD"},
{"number": 57, "emoji": "🎸", "description": "Guitar", "unicode": "U+1F3B8"},
{"number": 58, "emoji": "🎺", "description": "Trumpet", "unicode": "U+1F3BA"},
{"number": 59, "emoji": "🔔", "description": "Bell", "unicode": "U+1F514"},
{"number": 60, "emoji": "⚓", "description": "Anchor", "unicode": "U+2693"},
{"number": 61, "emoji": "🎧", "description": "Headphones", "unicode": "U+1F3A7"},
{"number": 62, "emoji": "📁", "description": "Folder", "unicode": "U+1F4C1"},
{"number": 63, "emoji": "📌", "description": "Pin", "unicode": "U+1F4CC"}
]

7
event-schemas/check_examples.py
Unescape Escape View File

@ -106,14 +106,17 @@ def check_example_dir(exampledir, schemadir):
if filename.startswith("."):
# Skip over any vim .swp files.
continue
if filename.endswith(".json"):
# Skip over any explicit examples (partial event definitions)
continue
cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
if cwd == "core":
# Skip checking the underlying definitions
continue
examplepath = os.path.join(root, filename)
schemapath = examplepath.replace(exampledir, schemadir)
if schemapath.find("#") >= 0:
schemapath = schemapath[:schemapath.find("#")]
if schemapath.find("$") >= 0:
schemapath = schemapath[:schemapath.find("$")]
try:
check_example_file(examplepath, schemapath)
except Exception as e:

18
event-schemas/examples/invite_room_state.json
Unescape Escape View File

@ -0,0 +1,18 @@
[
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]

4
event-schemas/examples/m.dummy
Unescape Escape View File

@ -0,0 +1,4 @@
{
"content": {},
"type": "m.dummy"
}

12
event-schemas/examples/m.key.verification.accept
Unescape Escape View File

@ -0,0 +1,12 @@
{
"type": "m.key.verification.accept",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocol": "curve25519",
"hash": "sha256",
"message_authentication_code": "hkdf-hmac-sha256",
"short_authentication_string": ["decimal", "emoji"],
"commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

8
event-schemas/examples/m.key.verification.cancel
Unescape Escape View File

@ -0,0 +1,8 @@
{
"type": "m.key.verification.cancel",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"code": "m.user",
"reason": "User rejected the key verification request"
}
}

7
event-schemas/examples/m.key.verification.key
Unescape Escape View File

@ -0,0 +1,7 @@
{
"type": "m.key.verification.key",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

10
event-schemas/examples/m.key.verification.mac
Unescape Escape View File

@ -0,0 +1,10 @@
{
"type": "m.key.verification.mac",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA",
"mac": {
"ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}

11
event-schemas/examples/m.key.verification.request
Unescape Escape View File

@ -0,0 +1,11 @@
{
"type": "m.key.verification.request",
"content": {
"from_device": "AliceDevice2",
"transaction_id": "S0meUniqueAndOpaqueString",
"methods": [
"m.sas.v1"
],
"timestamp": 1559598944869
}
}

8
event-schemas/examples/m.key.verification.start
Unescape Escape View File

@ -0,0 +1,8 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1"
}
}

12
event-schemas/examples/m.key.verification.start$m.sas.v1
Unescape Escape View File

@ -0,0 +1,12 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocols": ["curve25519"],
"hashes": ["sha256"],
"message_authentication_codes": ["hkdf-hmac-sha256"],
"short_authentication_string": ["decimal", "emoji"]
}
}

0
event-schemas/examples/m.room.encrypted#megolm → event-schemas/examples/m.room.encrypted$megolm
Unescape Escape View File

0
event-schemas/examples/m.room.encrypted#olm → event-schemas/examples/m.room.encrypted$olm
Unescape Escape View File

2
event-schemas/examples/m.room.member
Unescape Escape View File

@ -4,7 +4,7 @@
"type": "m.room.member",
"content": {
"membership": "join",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
}

27
event-schemas/examples/m.room.member#invite_room_state
Unescape Escape View File

@ -1,27 +0,0 @@
{
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
},
"unsigned": {
"age": 1234,
"invite_room_state": [
{
"type": "m.room.name",
"state_key": "",
"content": {
"name": "Forest of Magic"
}
},
{
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
}
}

14
event-schemas/examples/m.room.member$invite_room_state
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
},
"unsigned": {
"age": 1234,
"invite_room_state": {
"$ref": "invite_room_state.json"
}
}
}

2
event-schemas/examples/m.room.member#third_party_invite → event-schemas/examples/m.room.member$third_party_invite
Unescape Escape View File

@ -2,7 +2,7 @@
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"third_party_invite": {
"display_name": "alice",

0
event-schemas/examples/m.room.message#m.audio → event-schemas/examples/m.room.message$m.audio
Unescape Escape View File

0
event-schemas/examples/m.room.message#m.emote → event-schemas/examples/m.room.message$m.emote
Unescape Escape View File

Some files were not shown because too many files have changed in this diff Show More

Write Preview
Loading…
Cancel
Save