wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into travis/clarification/lowercasing

Browse source
This commit is contained in:
Travis Ralston 2021-05-18 09:55:57 -06:00 • committed by Richard van der Hoff
commit 21a132d3a5
21 changed files with 661 additions and 1380 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2985.clarification Normal file
View file

@ -0,0 +1 @@
Correct examples of `client_secret` request body parameters so that they do not include invalid characters.

1
changelogs/identity_service/newsfragments/3170.removal Normal file
View file

@ -0,0 +1 @@
The v1 identity service API has been removed in favour of the v2 API, as per [MSC2713](https://github.com/matrix-org/matrix-doc/pull/2713).

37
content/appendices.md
View file

@ -590,32 +590,6 @@ Event IDs and Room IDs are case-sensitive. They are not meant to be
human-readable. They are intended to be treated as fully opaque strings human-readable. They are intended to be treated as fully opaque strings
by clients. by clients.
#### Group Identifiers
Groups within Matrix are uniquely identified by their group ID. The
group ID is namespaced to the group server which hosts this group and
has the form:
+localpart:domain
The `localpart` of a group ID is an opaque identifier for that group. It
MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
`.`, `_`, `=`, `-`, and `/`.
The `domain` of a group ID is the [server name](#server-name) of the
group server which hosts this group.
The length of a group ID, including the `+` sigil and the domain, MUST
NOT exceed 255 characters.
The complete grammar for a legal group ID is:
group_id = "+" group_id_localpart ":" server_name
group_id_localpart = 1*group_id_char
group_id_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "." / "=" / "_" / "/"
#### Room Aliases #### Room Aliases
A room may have zero or more aliases. A room alias has the format: A room may have zero or more aliases. A room alias has the format:
@ -674,7 +648,6 @@ Examples of matrix.to URIs are:
- Permalink by room alias: - Permalink by room alias:
`https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org` `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
- User: `https://matrix.to/#/%40alice%3Aexample.org` - User: `https://matrix.to/#/%40alice%3Aexample.org`
- Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
{{% boxes/note %}} {{% boxes/note %}}
Historically, clients have not produced URIs which are fully encoded. Historically, clients have not produced URIs which are fully encoded.
@ -690,6 +663,16 @@ versions](/#room-versions). These slashes should normally be
encoded when producing matrix.to URIs, however. encoded when producing matrix.to URIs, however.
{{% /boxes/note %}} {{% /boxes/note %}}
{{% boxes/note %}}
<!-- TODO: @@TravisR: Make "Spaces" a link when that specification exists -->
In prior versions of this specification, a concept of "groups" were mentioned
to organize rooms. This functionality did not properly get introduced into
the specification and is subsequently replaced with "Spaces". Historical
matrix.to URIs pointing to groups might still exist: they take the form
`https://matrix.to/#/%2Bexample%3Aexample.org` (where the `+` sigil may or
may not be encoded).
{{% /boxes/note %}}
##### Routing ##### Routing
Room IDs are not routable on their own as there is no reliable domain to Room IDs are not routable on their own as there is no reliable domain to

2
content/client-server-api/_index.md
View file

@ -297,7 +297,7 @@ specify parameter values. The flow for this method is as follows:
6. If the `m.identity_server` property is present, extract the 6. If the `m.identity_server` property is present, extract the
`base_url` value for use as the base URL of the identity server. `base_url` value for use as the base URL of the identity server.
Validation for this URL is done as in the step above, but using Validation for this URL is done as in the step above, but using
`/_matrix/identity/api/v1` as the endpoint to connect to. If the `/_matrix/identity/v2` as the endpoint to connect to. If the
`m.identity_server` property is present, but does not have a `m.identity_server` property is present, but does not have a
`base_url` value, then `FAIL_PROMPT`. `base_url` value, then `FAIL_PROMPT`.

75
content/identity-service-api.md
View file

@ -59,48 +59,48 @@ the keys `error` and `errcode` MUST always be present.
Some standard error codes are below: Some standard error codes are below:
`M_NOT_FOUND` `M_NOT_FOUND`
The resource requested could not be located. The resource requested could not be located.
`M_MISSING_PARAMS` `M_MISSING_PARAMS`
The request was missing one or more parameters. The request was missing one or more parameters.
`M_INVALID_PARAM` `M_INVALID_PARAM`
The request contained one or more invalid parameters. The request contained one or more invalid parameters.
`M_SESSION_NOT_VALIDATED` `M_SESSION_NOT_VALIDATED`
The session has not been validated. The session has not been validated.
`M_NO_VALID_SESSION` `M_NO_VALID_SESSION`
A session could not be located for the given parameters. A session could not be located for the given parameters.
`M_SESSION_EXPIRED` `M_SESSION_EXPIRED`
The session has expired and must be renewed. The session has expired and must be renewed.
`M_INVALID_EMAIL` `M_INVALID_EMAIL`
The email address provided was not valid. The email address provided was not valid.
`M_EMAIL_SEND_ERROR` `M_EMAIL_SEND_ERROR`
There was an error sending an email. Typically seen when attempting to There was an error sending an email. Typically seen when attempting to
verify ownership of a given email address. verify ownership of a given email address.
`M_INVALID_ADDRESS` `M_INVALID_ADDRESS`
The provided third party address was not valid. The provided third party address was not valid.
`M_SEND_ERROR` `M_SEND_ERROR`
There was an error sending a notification. Typically seen when There was an error sending a notification. Typically seen when
attempting to verify ownership of a given third party address. attempting to verify ownership of a given third party address.
`M_UNRECOGNIZED` `M_UNRECOGNIZED`
The request contained an unrecognised value, such as an unknown token or The request contained an unrecognised value, such as an unknown token or
medium. medium.
`M_THREEPID_IN_USE` `M_THREEPID_IN_USE`
The third party identifier is already in use by another user. Typically The third party identifier is already in use by another user. Typically
this error will have an additional `mxid` property to indicate who owns this error will have an additional `mxid` property to indicate who owns
the third party identifier. the third party identifier.
`M_UNKNOWN` `M_UNKNOWN`
An unknown error has occurred. An unknown error has occurred.
{{% http-api spec="identity" api="versions" %}} {{% http-api spec="identity" api="versions" %}}
@ -116,22 +116,6 @@ Matrix user identity, but not in the other direction (i.e. one should
not be able to get all 3PIDs associated with a Matrix user ID, or get not be able to get all 3PIDs associated with a Matrix user ID, or get
all 3PIDs associated with a 3PID). all 3PIDs associated with a 3PID).
## Version 1 API deprecation
As described on each of the version 1 endpoints, the v1 API is
deprecated in favour of the v2 API described here. The major difference,
with the exception of a few isolated cases, is that the v2 API requires
authentication to ensure the user has given permission for the identity
server to operate on their data.
The v1 API is planned to be removed from the specification in a future
version.
Clients SHOULD attempt the v2 endpoints first, and if they receive a
`404`, `400`, or similar error they should try the v1 endpoint or fail
the operation. Clients are strongly encouraged to warn the user of the
risks in using the v1 API, if they are planning on using it.
## Web browser clients ## Web browser clients
It is realistic to expect that some clients will be written to be run It is realistic to expect that some clients will be written to be run
@ -149,12 +133,9 @@ recommended CORS headers to be returned by servers on all requests are:
## Authentication ## Authentication
Most `v2` endpoints in the Identity Service API require authentication Most endpoints in the Identity Service API require authentication
in order to ensure that the requesting user has accepted all relevant in order to ensure that the requesting user has accepted all relevant
policies and is otherwise permitted to make the request. The `v1` API policies and is otherwise permitted to make the request.
(currently deprecated) does not require this authentication, however
using `v1` is strongly discouraged as it will be removed in a future
release.
Identity Servers use a scheme similar to the Client-Server API's concept Identity Servers use a scheme similar to the Client-Server API's concept
of access tokens to authenticate users. The access tokens provided by an of access tokens to authenticate users. The access tokens provided by an
@ -204,8 +185,6 @@ has just accepted are appended to `m.accepted_terms`.
## Status check ## Status check
{{% http-api spec="identity" api="ping" %}}
{{% http-api spec="identity" api="v2_ping" %}} {{% http-api spec="identity" api="v2_ping" %}}
## Key management ## Key management
@ -219,23 +198,14 @@ The identity server may also keep track of some short-term
public-private keypairs, which may have different usage and lifetime public-private keypairs, which may have different usage and lifetime
characteristics than the service's long-term keys. characteristics than the service's long-term keys.
{{% http-api spec="identity" api="pubkey" %}}
{{% http-api spec="identity" api="v2_pubkey" %}} {{% http-api spec="identity" api="v2_pubkey" %}}
## Association lookup ## Association lookup
{{% http-api spec="identity" api="lookup" %}}
{{% http-api spec="identity" api="v2_lookup" %}} {{% http-api spec="identity" api="v2_lookup" %}}
### Client behaviour ### Client behaviour
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Prior to performing a lookup clients SHOULD make a request to the Prior to performing a lookup clients SHOULD make a request to the
`/hash_details` endpoint to determine what algorithms the server `/hash_details` endpoint to determine what algorithms the server
supports (described in more detail below). The client then uses this supports (described in more detail below). The client then uses this
@ -246,11 +216,6 @@ Clients MUST support at least the `sha256` algorithm.
### Server behaviour ### Server behaviour
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Servers, upon receipt of a `/lookup` request, will compare the query Servers, upon receipt of a `/lookup` request, will compare the query
against known bindings it has, hashing the identifiers it knows about as against known bindings it has, hashing the identifiers it knows about as
needed to verify exact matches to the request. needed to verify exact matches to the request.
@ -400,20 +365,14 @@ through without modification.
### Email associations ### Email associations
{{% http-api spec="identity" api="email_associations" %}}
{{% http-api spec="identity" api="v2_email_associations" %}} {{% http-api spec="identity" api="v2_email_associations" %}}
### Phone number associations ### Phone number associations
{{% http-api spec="identity" api="phone_associations" %}}
{{% http-api spec="identity" api="v2_phone_associations" %}} {{% http-api spec="identity" api="v2_phone_associations" %}}
### General ### General
{{% http-api spec="identity" api="associations" %}}
{{% http-api spec="identity" api="v2_associations" %}} {{% http-api spec="identity" api="v2_associations" %}}
## Invitation storage ## Invitation storage
@ -429,8 +388,6 @@ the Matrix user's homeserver via the
endpoint. The request MUST be signed with a long-term private key for endpoint. The request MUST be signed with a long-term private key for
the identity server. the identity server.
{{% http-api spec="identity" api="store_invite" %}}
{{% http-api spec="identity" api="v2_store_invite" %}} {{% http-api spec="identity" api="v2_store_invite" %}}
## Ephemeral invitation signing ## Ephemeral invitation signing
@ -440,6 +397,4 @@ identity server offers some crypto functionality to help in accepting
invitations. This is less secure than the client doing it itself, but invitations. This is less secure than the client doing it itself, but
may be useful where this isn't possible. may be useful where this isn't possible.
{{% http-api spec="identity" api="invitation_signing" %}}
{{% http-api spec="identity" api="v2_invitation_signing" %}} {{% http-api spec="identity" api="v2_invitation_signing" %}}

50
content/proposals.md
View file

@ -245,10 +245,13 @@ is as follows:
75% of the members of the Spec Core Team agree on its outcome, and 75% of the members of the Spec Core Team agree on its outcome, and
all existing concerns have been resolved. all existing concerns have been resolved.
- The FCP will then begin and last for 5 days, giving anyone else some - The FCP will then begin and last for 5 days, giving anyone else some
time to speak up before it concludes. On its conclusion, the time to speak up before it concludes. If sufficient reasoning
disposition of the FCP will be carried out. If sufficient reasoning against the disposition is provided, a member of the Spec Core Team can
against the disposition is raised, the FCP can be cancelled and the raise a concern and block FCP from completing. This will not reset or
MSC will continue to evolve accordingly. pause the 5 day FCP timer, but FCP will not conclude until all concerns have
been resolved. If sufficient change in the MSC is required to resolve those
concerns, FCP might be cancelled and reproposed. Once FCP has concluded,
the disposition of the FCP will be carried out.
- Once the proposal has been accepted and merged, it is time to submit - Once the proposal has been accepted and merged, it is time to submit
the actual change to the Specification that your proposal reasoned the actual change to the Specification that your proposal reasoned
about. This is known as a spec PR. However in order for the spec PR about. This is known as a spec PR. However in order for the spec PR
@ -259,7 +262,7 @@ is as follows:
will warrant another MSC. Any minor, non-fundamental changes are will warrant another MSC. Any minor, non-fundamental changes are
allowed but **must** be documented in the original proposal allowed but **must** be documented in the original proposal
document. This ensures that someone reading a proposal in the future document. This ensures that someone reading a proposal in the future
doesn't assume old information wasn't merged into the spec. doesn't assume old information that wasn't merged into the spec.
- Similar to the proposal PR, please sign off the spec PR as per - Similar to the proposal PR, please sign off the spec PR as per
the guidelines on the guidelines on
[CONTRIBUTING.rst](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst). [CONTRIBUTING.rst](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst).
@ -373,7 +376,7 @@ be merged without the Spec Core Team focusing on them specifically.
## Implementing a proposal ## Implementing a proposal
As part of the proposal process the spec core team will require evidence As part of the proposal process the Spec Core Team will require evidence
of the MSC working in order for it to move into FCP. This can usually be of the MSC working in order for it to move into FCP. This can usually be
a branch/pull request to whichever implementation of choice that proves a branch/pull request to whichever implementation of choice that proves
the MSC works in practice, though in some cases the MSC itself will be the MSC works in practice, though in some cases the MSC itself will be
@ -388,13 +391,11 @@ release, implementations are required to use the following process to
ensure that the official Matrix namespace is not cluttered with ensure that the official Matrix namespace is not cluttered with
development or testing data. development or testing data.
Note **Note:** Unreleased implementations (including proofs-of-concept demonstrating
Unreleased implementations (including proofs-of-concept demonstrating
that a particular MSC works) do not have to follow this process. that a particular MSC works) do not have to follow this process.
1. Have an idea for a feature. 1. Have an idea for a feature.
2. Implement the feature using unstable endpoints, vendor prefixes, and 1. Implement the feature using unstable endpoints, vendor prefixes, and
unstable feature flags as appropriate. unstable feature flags as appropriate.
- When using unstable endpoints, they MUST include a vendor - When using unstable endpoints, they MUST include a vendor
prefix. For example: prefix. For example:
@ -429,22 +430,25 @@ that a particular MSC works) do not have to follow this process.
- If at any point after early release, the idea changes in a - If at any point after early release, the idea changes in a
backwards-incompatible way, the feature flag should also change backwards-incompatible way, the feature flag should also change
so that implementations can adapt as needed. so that implementations can adapt as needed.
3. In parallel, or ahead of implementation, open an MSC and solicit 1. In parallel, or ahead of implementation, open an MSC and solicit
review per above. review per above.
4. Before FCP can be called, the Spec Core Team will require evidence 1. Before FCP can be called, the Spec Core Team will require evidence
of the MSC working as proposed. A typical example of this is an of the MSC working as proposed. A typical example of this is an
implementation of the MSC, though the implementation does not need implementation of the MSC, though the implementation does not need
to be shipped anywhere and can therefore avoid the to be shipped anywhere and can therefore avoid the
forwards/backwards compatibility concerns mentioned here. forwards/backwards compatibility concerns mentioned here.
5. The FCP process is completed, and assuming nothing is flagged the 1. The FCP process is completed, and assuming nothing is flagged the
MSC lands. MSC lands.
6. A spec PR is written to incorporate the changes into Matrix. 1. Implementations can now switch to using stable prefixes
7. A spec release happens. (for example, for an endpoint, moving from
8. Implementations switch to using stable prefixes (e.g.: `/r0`) if the `/unstable/org.matrix.mscxxxx/frobnicate`
server supports the specification version released. If the server to `/v1/frobnicate`), assuming that the change
doesn't advertise the specification version, but does have the is backwards compatible with older implementations. In the rare occasion
feature flag, unstable prefixes should still be used. where backwards compatibility is not possible without a new spec release,
9. A transition period of about 2 months starts immediately after the implementations should continue to use unstable prefixes.
1. A spec PR is written to incorporate the changes into Matrix.
1. A spec release happens.
1. A transition period of about 2 months starts immediately after the
spec release, before implementations start to encourage other spec release, before implementations start to encourage other
implementations to switch to stable endpoints. For example, a server implementations to switch to stable endpoints. For example, a server
implementation should start asking client implementations to support implementation should start asking client implementations to support
@ -463,9 +467,9 @@ com.example/new/endpoint`.
In summary: In summary:
- Implementations MUST NOT use stable endpoints before the MSC is in - Implementations MUST NOT use stable endpoints before the MSC has
the spec. This includes NOT using stable endpoints in the period completed FCP. Once that has occurred, implementations are allowed
between completion of FCP and release of the spec. passed. to use stable endpoints, but are not required to.
- Implementations are able to ship features that are exposed to users - Implementations are able to ship features that are exposed to users
by default before an MSC has been merged to the spec, provided they by default before an MSC has been merged to the spec, provided they
follow the process above. follow the process above.

66
data-definitions/sas-emoji-v1-i18n/hu.json Normal file
View file

@ -0,0 +1,66 @@
{
"Pin": "Rajszeg",
"Folder": "Mappa",
"Headphones": "Fejhallgató",
"Anchor": "Horgony",
"Bell": "Harang",
"Trumpet": "Trombita",
"Guitar": "Gitár",
"Ball": "Labda",
"Trophy": "Trófea",
"Rocket": "Rakáta",
"Aeroplane": "Repülő",
"Bicycle": "Kerékpár",
"Train": "Vonat",
"Flag": "Zászló",
"Telephone": "Telefon",
"Hammer": "Kalapács",
"Key": "Kulcs",
"Lock": "Lakat",
"Scissors": "Olló",
"Paperclip": "Gémkapocs",
"Pencil": "Ceruza",
"Book": "Könyv",
"Light Bulb": "Égő",
"Gift": "Ajándék",
"Clock": "Óra",
"Hourglass": "Homokóra",
"Umbrella": "Esernyő",
"Thumbs Up": "Hüvelykujj fel",
"Santa": "Télapó",
"Spanner": "Csavarkulcs",
"Glasses": "Szemüveg",
"Hat": "Kalap",
"Robot": "Robot",
"Smiley": "Mosoly",
"Heart": "Szív",
"Cake": "Süti",
"Pizza": "Pizza",
"Corn": "Kukorica",
"Strawberry": "Eper",
"Apple": "Alma",
"Banana": "Banán",
"Fire": "Tűz",
"Cloud": "Felhő",
"Moon": "Hold",
"Globe": "Földgömb",
"Mushroom": "Gomba",
"Cactus": "Kaktusz",
"Tree": "Fa",
"Flower": "Virág",
"Butterfly": "Pillangó",
"Octopus": "Polip",
"Fish": "Hal",
"Turtle": "Teknős",
"Penguin": "Pingvin",
"Rooster": "Kakas",
"Panda": "Panda",
"Rabbit": "Nyúl",
"Elephant": "Elefánt",
"Pig": "Malac",
"Unicorn": "Egyszarvú",
"Horse": "Ló",
"Lion": "Oroszlán",
"Cat": "Macska",
"Dog": "Kutya"
}

64
data-definitions/sas-emoji.json
View file

@ -16,6 +16,7 @@
"fi": "Koira", "fi": "Koira",
"fr": "Chien", "fr": "Chien",
"hr": "pas", "hr": "pas",
"hu": "Kutya",
"it": "Cane", "it": "Cane",
"ja": "犬", "ja": "犬",
"nb_NO": "Hund", "nb_NO": "Hund",
@ -49,6 +50,7 @@
"fi": "Kissa", "fi": "Kissa",
"fr": "Chat", "fr": "Chat",
"hr": "mačka", "hr": "mačka",
"hu": "Macska",
"it": "Gatto", "it": "Gatto",
"ja": "猫", "ja": "猫",
"nb_NO": "Katt", "nb_NO": "Katt",
@ -82,6 +84,7 @@
"fi": "Leijona", "fi": "Leijona",
"fr": "Lion", "fr": "Lion",
"hr": "lav", "hr": "lav",
"hu": "Oroszlán",
"it": "Leone", "it": "Leone",
"ja": "ライオン", "ja": "ライオン",
"nb_NO": "Løve", "nb_NO": "Løve",
@ -115,6 +118,7 @@
"fi": "Hevonen", "fi": "Hevonen",
"fr": "Cheval", "fr": "Cheval",
"hr": "konj", "hr": "konj",
"hu": "Ló",
"it": "Cavallo", "it": "Cavallo",
"ja": "馬", "ja": "馬",
"nb_NO": "Hest", "nb_NO": "Hest",
@ -148,6 +152,7 @@
"fi": "Yksisarvinen", "fi": "Yksisarvinen",
"fr": "Licorne", "fr": "Licorne",
"hr": "jednorog", "hr": "jednorog",
"hu": "Egyszarvú",
"it": "Unicorno", "it": "Unicorno",
"ja": "ユニコーン", "ja": "ユニコーン",
"nb_NO": "Enhjørning", "nb_NO": "Enhjørning",
@ -181,6 +186,7 @@
"fi": "Sika", "fi": "Sika",
"fr": "Cochon", "fr": "Cochon",
"hr": "svinja", "hr": "svinja",
"hu": "Malac",
"it": "Maiale", "it": "Maiale",
"ja": "ブタ", "ja": "ブタ",
"nb_NO": "Gris", "nb_NO": "Gris",
@ -214,6 +220,7 @@
"fi": "Norsu", "fi": "Norsu",
"fr": "Éléphant", "fr": "Éléphant",
"hr": "slon", "hr": "slon",
"hu": "Elefánt",
"it": "Elefante", "it": "Elefante",
"ja": "ゾウ", "ja": "ゾウ",
"nb_NO": "Elefant", "nb_NO": "Elefant",
@ -247,6 +254,7 @@
"fi": "Kani", "fi": "Kani",
"fr": "Lapin", "fr": "Lapin",
"hr": "zec", "hr": "zec",
"hu": "Nyúl",
"it": "Coniglio", "it": "Coniglio",
"ja": "うさぎ", "ja": "うさぎ",
"nb_NO": "Kanin", "nb_NO": "Kanin",
@ -280,6 +288,7 @@
"fi": "Panda", "fi": "Panda",
"fr": "Panda", "fr": "Panda",
"hr": "panda", "hr": "panda",
"hu": "Panda",
"it": "Panda", "it": "Panda",
"ja": "パンダ", "ja": "パンダ",
"nb_NO": "Panda", "nb_NO": "Panda",
@ -313,6 +322,7 @@
"fi": "Kukko", "fi": "Kukko",
"fr": "Coq", "fr": "Coq",
"hr": "kokot", "hr": "kokot",
"hu": "Kakas",
"it": "Gallo", "it": "Gallo",
"ja": "ニワトリ", "ja": "ニワトリ",
"nb_NO": "Hane", "nb_NO": "Hane",
@ -346,6 +356,7 @@
"fi": "Pingviini", "fi": "Pingviini",
"fr": "Manchot", "fr": "Manchot",
"hr": "pingvin", "hr": "pingvin",
"hu": "Pingvin",
"it": "Pinguino", "it": "Pinguino",
"ja": "ペンギン", "ja": "ペンギン",
"nb_NO": "Pingvin", "nb_NO": "Pingvin",
@ -379,6 +390,7 @@
"fi": "Kilpikonna", "fi": "Kilpikonna",
"fr": "Tortue", "fr": "Tortue",
"hr": "kornjača", "hr": "kornjača",
"hu": "Teknős",
"it": "Tartaruga", "it": "Tartaruga",
"ja": "亀", "ja": "亀",
"nb_NO": "Skilpadde", "nb_NO": "Skilpadde",
@ -412,6 +424,7 @@
"fi": "Kala", "fi": "Kala",
"fr": "Poisson", "fr": "Poisson",
"hr": "riba", "hr": "riba",
"hu": "Hal",
"it": "Pesce", "it": "Pesce",
"ja": "魚", "ja": "魚",
"nb_NO": "Fisk", "nb_NO": "Fisk",
@ -445,6 +458,7 @@
"fi": "Tursas", "fi": "Tursas",
"fr": "Poulpe", "fr": "Poulpe",
"hr": "hobotnica", "hr": "hobotnica",
"hu": "Polip",
"it": "Polpo", "it": "Polpo",
"ja": "たこ", "ja": "たこ",
"nb_NO": "Blekksprut", "nb_NO": "Blekksprut",
@ -478,6 +492,7 @@
"fi": "Perhonen", "fi": "Perhonen",
"fr": "Papillon", "fr": "Papillon",
"hr": "leptir", "hr": "leptir",
"hu": "Pillangó",
"it": "Farfalla", "it": "Farfalla",
"ja": "ちょうちょ", "ja": "ちょうちょ",
"nb_NO": "Sommerfugl", "nb_NO": "Sommerfugl",
@ -511,6 +526,7 @@
"fi": "Kukka", "fi": "Kukka",
"fr": "Fleur", "fr": "Fleur",
"hr": "svijet", "hr": "svijet",
"hu": "Virág",
"it": "Fiore", "it": "Fiore",
"ja": "花", "ja": "花",
"nb_NO": "Blomst", "nb_NO": "Blomst",
@ -544,6 +560,7 @@
"fi": "Puu", "fi": "Puu",
"fr": "Arbre", "fr": "Arbre",
"hr": "drvo", "hr": "drvo",
"hu": "Fa",
"it": "Albero", "it": "Albero",
"ja": "木", "ja": "木",
"nb_NO": "Tre", "nb_NO": "Tre",
@ -577,6 +594,7 @@
"fi": "Kaktus", "fi": "Kaktus",
"fr": "Cactus", "fr": "Cactus",
"hr": "kaktus", "hr": "kaktus",
"hu": "Kaktusz",
"it": "Cactus", "it": "Cactus",
"ja": "サボテン", "ja": "サボテン",
"nb_NO": "Kaktus", "nb_NO": "Kaktus",
@ -610,6 +628,7 @@
"fi": "Sieni", "fi": "Sieni",
"fr": "Champignon", "fr": "Champignon",
"hr": "gljiva", "hr": "gljiva",
"hu": "Gomba",
"it": "Fungo", "it": "Fungo",
"ja": "きのこ", "ja": "きのこ",
"nb_NO": "Sopp", "nb_NO": "Sopp",
@ -643,6 +662,7 @@
"fi": "Maapallo", "fi": "Maapallo",
"fr": "Globe", "fr": "Globe",
"hr": "Globus", "hr": "Globus",
"hu": "Földgömb",
"it": "Globo", "it": "Globo",
"ja": "地球", "ja": "地球",
"nb_NO": "Globus", "nb_NO": "Globus",
@ -676,6 +696,7 @@
"fi": "Kuu", "fi": "Kuu",
"fr": "Lune", "fr": "Lune",
"hr": "mjesec", "hr": "mjesec",
"hu": "Hold",
"it": "Luna", "it": "Luna",
"ja": "月", "ja": "月",
"nb_NO": "Måne", "nb_NO": "Måne",
@ -709,6 +730,7 @@
"fi": "Pilvi", "fi": "Pilvi",
"fr": "Nuage", "fr": "Nuage",
"hr": "oblak", "hr": "oblak",
"hu": "Felhő",
"it": "Nuvola", "it": "Nuvola",
"ja": "雲", "ja": "雲",
"nb_NO": "Sky", "nb_NO": "Sky",
@ -742,6 +764,7 @@
"fi": "Tuli", "fi": "Tuli",
"fr": "Feu", "fr": "Feu",
"hr": "vatra", "hr": "vatra",
"hu": "Tűz",
"it": "Fuoco", "it": "Fuoco",
"ja": "炎", "ja": "炎",
"nb_NO": "Flamme", "nb_NO": "Flamme",
@ -775,6 +798,7 @@
"fi": "Banaani", "fi": "Banaani",
"fr": "Banane", "fr": "Banane",
"hr": "banana", "hr": "banana",
"hu": "Banán",
"it": "Banana", "it": "Banana",
"ja": "バナナ", "ja": "バナナ",
"nb_NO": "Banan", "nb_NO": "Banan",
@ -808,6 +832,7 @@
"fi": "Omena", "fi": "Omena",
"fr": "Pomme", "fr": "Pomme",
"hr": "jabuka", "hr": "jabuka",
"hu": "Alma",
"it": "Mela", "it": "Mela",
"ja": "リンゴ", "ja": "リンゴ",
"nb_NO": "Eple", "nb_NO": "Eple",
@ -841,6 +866,7 @@
"fi": "Mansikka", "fi": "Mansikka",
"fr": "Fraise", "fr": "Fraise",
"hr": "jagoda", "hr": "jagoda",
"hu": "Eper",
"it": "Fragola", "it": "Fragola",
"ja": "いちご", "ja": "いちご",
"nb_NO": "Jordbær", "nb_NO": "Jordbær",
@ -874,6 +900,7 @@
"fi": "Maissi", "fi": "Maissi",
"fr": "Maïs", "fr": "Maïs",
"hr": "kukuruza", "hr": "kukuruza",
"hu": "Kukorica",
"it": "Mais", "it": "Mais",
"ja": "とうもろこし", "ja": "とうもろこし",
"nb_NO": "Mais", "nb_NO": "Mais",
@ -907,6 +934,7 @@
"fi": "Pizza", "fi": "Pizza",
"fr": "Pizza", "fr": "Pizza",
"hr": "pizza", "hr": "pizza",
"hu": "Pizza",
"it": "Pizza", "it": "Pizza",
"ja": "ピザ", "ja": "ピザ",
"nb_NO": "Pizza", "nb_NO": "Pizza",
@ -940,6 +968,7 @@
"fi": "Kakku", "fi": "Kakku",
"fr": "Gâteau", "fr": "Gâteau",
"hr": "torta", "hr": "torta",
"hu": "Süti",
"it": "Torta", "it": "Torta",
"ja": "ケーキ", "ja": "ケーキ",
"nb_NO": "Kake", "nb_NO": "Kake",
@ -973,6 +1002,7 @@
"fi": "Sydän", "fi": "Sydän",
"fr": "Cœur", "fr": "Cœur",
"hr": "srca", "hr": "srca",
"hu": "Szív",
"it": "Cuore", "it": "Cuore",
"ja": "ハート", "ja": "ハート",
"nb_NO": "Hjerte", "nb_NO": "Hjerte",
@ -1006,6 +1036,7 @@
"fi": "Hymynaama", "fi": "Hymynaama",
"fr": "Sourire", "fr": "Sourire",
"hr": "smajlića", "hr": "smajlića",
"hu": "Mosoly",
"it": "Faccina sorridente", "it": "Faccina sorridente",
"ja": "スマイル", "ja": "スマイル",
"nb_NO": "Smilefjes", "nb_NO": "Smilefjes",
@ -1039,6 +1070,7 @@
"fi": "Robotti", "fi": "Robotti",
"fr": "Robot", "fr": "Robot",
"hr": "robot", "hr": "robot",
"hu": "Robot",
"it": "Robot", "it": "Robot",
"ja": "ロボと", "ja": "ロボと",
"nb_NO": "Robot", "nb_NO": "Robot",
@ -1072,6 +1104,7 @@
"fi": "Hattu", "fi": "Hattu",
"fr": "Chapeau", "fr": "Chapeau",
"hr": "kapa", "hr": "kapa",
"hu": "Kalap",
"it": "Cappello", "it": "Cappello",
"ja": "帽子", "ja": "帽子",
"nb_NO": "Hatt", "nb_NO": "Hatt",
@ -1105,6 +1138,7 @@
"fi": "Silmälasit", "fi": "Silmälasit",
"fr": "Lunettes", "fr": "Lunettes",
"hr": "naočale", "hr": "naočale",
"hu": "Szemüveg",
"it": "Occhiali", "it": "Occhiali",
"ja": "めがね", "ja": "めがね",
"nb_NO": "Briller", "nb_NO": "Briller",
@ -1138,6 +1172,7 @@
"fi": "Kiintoavain", "fi": "Kiintoavain",
"fr": "Clé à molette", "fr": "Clé à molette",
"hr": "ključ", "hr": "ključ",
"hu": "Csavarkulcs",
"it": "Chiave inglese", "it": "Chiave inglese",
"ja": "スパナ", "ja": "スパナ",
"nb_NO": "Fastnøkkel", "nb_NO": "Fastnøkkel",
@ -1171,6 +1206,7 @@
"fi": "Joulupukki", "fi": "Joulupukki",
"fr": "Père Noël", "fr": "Père Noël",
"hr": "deda Mraz", "hr": "deda Mraz",
"hu": "Télapó",
"it": "Babbo Natale", "it": "Babbo Natale",
"ja": "サンタ", "ja": "サンタ",
"nb_NO": "Julenisse", "nb_NO": "Julenisse",
@ -1204,6 +1240,7 @@
"fi": "Peukalo ylös", "fi": "Peukalo ylös",
"fr": "Pouce en l’air", "fr": "Pouce en l’air",
"hr": "palac gore", "hr": "palac gore",
"hu": "Hüvelykujj fel",
"it": "Pollice alzato", "it": "Pollice alzato",
"ja": "いいね", "ja": "いいね",
"nb_NO": "Tommel Opp", "nb_NO": "Tommel Opp",
@ -1237,6 +1274,7 @@
"fi": "Sateenvarjo", "fi": "Sateenvarjo",
"fr": "Parapluie", "fr": "Parapluie",
"hr": "kišobran", "hr": "kišobran",
"hu": "Esernyő",
"it": "Ombrello", "it": "Ombrello",
"ja": "傘", "ja": "傘",
"nb_NO": "Paraply", "nb_NO": "Paraply",
@ -1270,6 +1308,7 @@
"fi": "Tiimalasi", "fi": "Tiimalasi",
"fr": "Sablier", "fr": "Sablier",
"hr": "pješčani sat", "hr": "pješčani sat",
"hu": "Homokóra",
"it": "Clessidra", "it": "Clessidra",
"ja": "砂時計", "ja": "砂時計",
"nb_NO": "Timeglass", "nb_NO": "Timeglass",
@ -1303,6 +1342,7 @@
"fi": "Pöytäkello", "fi": "Pöytäkello",
"fr": "Réveil", "fr": "Réveil",
"hr": "sat", "hr": "sat",
"hu": "Óra",
"it": "Orologio", "it": "Orologio",
"ja": "時計", "ja": "時計",
"nb_NO": "Klokke", "nb_NO": "Klokke",
@ -1336,6 +1376,7 @@
"fi": "Lahja", "fi": "Lahja",
"fr": "Cadeau", "fr": "Cadeau",
"hr": "poklon", "hr": "poklon",
"hu": "Ajándék",
"it": "Regalo", "it": "Regalo",
"ja": "ギフト", "ja": "ギフト",
"nb_NO": "Gave", "nb_NO": "Gave",
@ -1369,6 +1410,7 @@
"fi": "Hehkulamppu", "fi": "Hehkulamppu",
"fr": "Ampoule", "fr": "Ampoule",
"hr": "žarulja", "hr": "žarulja",
"hu": "Égő",
"it": "Lampadina", "it": "Lampadina",
"ja": "電球", "ja": "電球",
"nb_NO": "Lyspære", "nb_NO": "Lyspære",
@ -1402,6 +1444,7 @@
"fi": "Kirja", "fi": "Kirja",
"fr": "Livre", "fr": "Livre",
"hr": "knjiga", "hr": "knjiga",
"hu": "Könyv",
"it": "Libro", "it": "Libro",
"ja": "本", "ja": "本",
"nb_NO": "Bok", "nb_NO": "Bok",
@ -1435,6 +1478,7 @@
"fi": "Lyijykynä", "fi": "Lyijykynä",
"fr": "Crayon", "fr": "Crayon",
"hr": "olovka", "hr": "olovka",
"hu": "Ceruza",
"it": "Matita", "it": "Matita",
"ja": "鉛筆", "ja": "鉛筆",
"nb_NO": "Blyant", "nb_NO": "Blyant",
@ -1468,6 +1512,7 @@
"fi": "Paperiliitin", "fi": "Paperiliitin",
"fr": "Trombone", "fr": "Trombone",
"hr": "spajalica", "hr": "spajalica",
"hu": "Gémkapocs",
"it": "Graffetta", "it": "Graffetta",
"ja": "クリップ", "ja": "クリップ",
"nb_NO": "BInders", "nb_NO": "BInders",
@ -1501,6 +1546,7 @@
"fi": "Sakset", "fi": "Sakset",
"fr": "Ciseaux", "fr": "Ciseaux",
"hr": "škare", "hr": "škare",
"hu": "Olló",
"it": "Forbici", "it": "Forbici",
"ja": "はさみ", "ja": "はさみ",
"nb_NO": "Saks", "nb_NO": "Saks",
@ -1534,6 +1580,7 @@
"fi": "Lukko", "fi": "Lukko",
"fr": "Cadenas", "fr": "Cadenas",
"hr": "zaključati", "hr": "zaključati",
"hu": "Lakat",
"it": "Lucchetto", "it": "Lucchetto",
"ja": "錠前", "ja": "錠前",
"nb_NO": "Lås", "nb_NO": "Lås",
@ -1567,6 +1614,7 @@
"fi": "Avain", "fi": "Avain",
"fr": "Clé", "fr": "Clé",
"hr": "ključ", "hr": "ključ",
"hu": "Kulcs",
"it": "Chiave", "it": "Chiave",
"ja": "鍵", "ja": "鍵",
"nb_NO": "Nøkkel", "nb_NO": "Nøkkel",
@ -1600,6 +1648,7 @@
"fi": "Vasara", "fi": "Vasara",
"fr": "Marteau", "fr": "Marteau",
"hr": "čekić", "hr": "čekić",
"hu": "Kalapács",
"it": "Martello", "it": "Martello",
"ja": "金槌", "ja": "金槌",
"nb_NO": "Hammer", "nb_NO": "Hammer",
@ -1633,6 +1682,7 @@
"fi": "Puhelin", "fi": "Puhelin",
"fr": "Téléphone", "fr": "Téléphone",
"hr": "telefon", "hr": "telefon",
"hu": "Telefon",
"it": "Telefono", "it": "Telefono",
"ja": "電話機", "ja": "電話機",
"nb_NO": "Telefon", "nb_NO": "Telefon",
@ -1666,6 +1716,7 @@
"fi": "Lippu", "fi": "Lippu",
"fr": "Drapeau", "fr": "Drapeau",
"hr": "zastava", "hr": "zastava",
"hu": "Zászló",
"it": "Bandiera", "it": "Bandiera",
"ja": "旗", "ja": "旗",
"nb_NO": "Flagg", "nb_NO": "Flagg",
@ -1699,6 +1750,7 @@
"fi": "Juna", "fi": "Juna",
"fr": "Train", "fr": "Train",
"hr": "vlak", "hr": "vlak",
"hu": "Vonat",
"it": "Treno", "it": "Treno",
"ja": "電車", "ja": "電車",
"nb_NO": "Tog", "nb_NO": "Tog",
@ -1732,6 +1784,7 @@
"fi": "Polkupyörä", "fi": "Polkupyörä",
"fr": "Vélo", "fr": "Vélo",
"hr": "bicikl", "hr": "bicikl",
"hu": "Kerékpár",
"it": "Bicicletta", "it": "Bicicletta",
"ja": "自転車", "ja": "自転車",
"nb_NO": "Sykkel", "nb_NO": "Sykkel",
@ -1765,6 +1818,7 @@
"fi": "Lentokone", "fi": "Lentokone",
"fr": "Avion", "fr": "Avion",
"hr": "avion", "hr": "avion",
"hu": "Repülő",
"it": "Aeroplano", "it": "Aeroplano",
"ja": "飛行機", "ja": "飛行機",
"nb_NO": "Fly", "nb_NO": "Fly",
@ -1798,6 +1852,7 @@
"fi": "Raketti", "fi": "Raketti",
"fr": "Fusée", "fr": "Fusée",
"hr": "raketa", "hr": "raketa",
"hu": "Rakáta",
"it": "Razzo", "it": "Razzo",
"ja": "ロケット", "ja": "ロケット",
"nb_NO": "Rakett", "nb_NO": "Rakett",
@ -1831,6 +1886,7 @@
"fi": "Palkinto", "fi": "Palkinto",
"fr": "Trophée", "fr": "Trophée",
"hr": "trofej", "hr": "trofej",
"hu": "Trófea",
"it": "Trofeo", "it": "Trofeo",
"ja": "トロフィー", "ja": "トロフィー",
"nb_NO": "Pokal", "nb_NO": "Pokal",
@ -1864,6 +1920,7 @@
"fi": "Pallo", "fi": "Pallo",
"fr": "Ballon", "fr": "Ballon",
"hr": "lopta", "hr": "lopta",
"hu": "Labda",
"it": "Palla", "it": "Palla",
"ja": "ボール", "ja": "ボール",
"nb_NO": "Ball", "nb_NO": "Ball",
@ -1897,6 +1954,7 @@
"fi": "Kitara", "fi": "Kitara",
"fr": "Guitare", "fr": "Guitare",
"hr": "gitara", "hr": "gitara",
"hu": "Gitár",
"it": "Chitarra", "it": "Chitarra",
"ja": "ギター", "ja": "ギター",
"nb_NO": "Gitar", "nb_NO": "Gitar",
@ -1930,6 +1988,7 @@
"fi": "Trumpetti", "fi": "Trumpetti",
"fr": "Trompette", "fr": "Trompette",
"hr": "truba", "hr": "truba",
"hu": "Trombita",
"it": "Trombetta", "it": "Trombetta",
"ja": "トランペット", "ja": "トランペット",
"nb_NO": "Trompet", "nb_NO": "Trompet",
@ -1963,6 +2022,7 @@
"fi": "Soittokello", "fi": "Soittokello",
"fr": "Cloche", "fr": "Cloche",
"hr": "zvono", "hr": "zvono",
"hu": "Harang",
"it": "Campana", "it": "Campana",
"ja": "ベル", "ja": "ベル",
"nb_NO": "Bjelle", "nb_NO": "Bjelle",
@ -1996,6 +2056,7 @@
"fi": "Ankkuri", "fi": "Ankkuri",
"fr": "Ancre", "fr": "Ancre",
"hr": "sidro", "hr": "sidro",
"hu": "Horgony",
"it": "Ancora", "it": "Ancora",
"ja": "いかり", "ja": "いかり",
"nb_NO": "Anker", "nb_NO": "Anker",
@ -2029,6 +2090,7 @@
"fi": "Kuulokkeet", "fi": "Kuulokkeet",
"fr": "Casque audio", "fr": "Casque audio",
"hr": "slušalice", "hr": "slušalice",
"hu": "Fejhallgató",
"it": "Cuffie", "it": "Cuffie",
"ja": "ヘッドホン", "ja": "ヘッドホン",
"nb_NO": "Hodetelefoner", "nb_NO": "Hodetelefoner",
@ -2062,6 +2124,7 @@
"fi": "Kansio", "fi": "Kansio",
"fr": "Dossier", "fr": "Dossier",
"hr": "mapu", "hr": "mapu",
"hu": "Mappa",
"it": "Cartella", "it": "Cartella",
"ja": "フォルダ", "ja": "フォルダ",
"nb_NO": "Mappe", "nb_NO": "Mappe",
@ -2095,6 +2158,7 @@
"fi": "Nuppineula", "fi": "Nuppineula",
"fr": "Punaise", "fr": "Punaise",
"hr": "pribadača", "hr": "pribadača",
"hu": "Rajszeg",
"it": "Puntina", "it": "Puntina",
"ja": "ピン", "ja": "ピン",
"nb_NO": "Tegnestift", "nb_NO": "Tegnestift",

8
data/api/client-server/administrative_contact.yaml
View file

@ -139,7 +139,7 @@ paths:
"id_server": "matrix.org", "id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString", "id_access_token": "abc123_OpaqueString",
"sid": "abc123987", "sid": "abc123987",
"client_secret": "d0n'tT3ll" "client_secret": "d0nt-T3ll"
} }
} }
responses: responses:
@ -215,7 +215,7 @@ paths:
required: ["client_secret", "sid"] required: ["client_secret", "sid"]
example: { example: {
"sid": "abc123987", "sid": "abc123987",
"client_secret": "d0n'tT3ll" "client_secret": "d0nt-T3ll"
} }
responses: responses:
200: 200:
@ -233,6 +233,8 @@ paths:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:
"$ref": "definitions/errors/rate_limited.yaml" "$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/3pid/bind": "/account/3pid/bind":
post: post:
summary: Binds a 3PID to the user's account through an Identity Service. summary: Binds a 3PID to the user's account through an Identity Service.
@ -272,7 +274,7 @@ paths:
"id_server": "example.org", "id_server": "example.org",
"id_access_token": "abc123_OpaqueString", "id_access_token": "abc123_OpaqueString",
"sid": "abc123987", "sid": "abc123987",
"client_secret": "d0n'tT3ll" "client_secret": "d0nt-T3ll"
} }
responses: responses:
200: 200:

2
data/api/client-server/appservice_room_directory.yaml
View file

@ -43,7 +43,7 @@ paths:
This API requires the use of an application service access token (`as_token`) This API requires the use of an application service access token (`as_token`)
instead of a typical client's access_token. This API cannot be invoked by instead of a typical client's access_token. This API cannot be invoked by
users who are not identified as application services. users who are not identified as application services.
operationId: updateAppserviceRoomDirectoryVsibility operationId: updateAppserviceRoomDirectoryVisibility
parameters: parameters:
- in: path - in: path
type: string type: string

302
data/api/identity/associations.yaml
View file

@ -1,302 +0,0 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Establishing Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: |-
Determines if a given 3pid has been validated by a user.
operationId: getValidated3pid
deprecated: true
parameters:
- in: query
type: string
name: sid
description: The Session ID generated by the `requestToken` call.
required: true
x-example: 1234
- in: query
type: string
name: client_secret
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
200:
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
description: |-
The session has not been validated.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
Publish an association between a session and a Matrix user ID.
Future calls to `/lookup` for any of the session\'s 3pids will return
this association.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: bind
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required: ["sid", "client_secret", "mxid"]
responses:
200:
description: The association was published.
examples:
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
description: A unix timestamp before which the association is not known to be valid.
not_after:
type: integer
description: A unix timestamp after which the association is not known to be valid.
ts:
type: integer
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
$ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
400:
description: |-
The association was not published.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/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
deprecated: true
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](/appendices/#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.

177
data/api/identity/email_associations.yaml
View file

@ -1,177 +0,0 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Email Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/validate/email/requestToken":
post:
summary: Request a token for validating an email address.
description: |-
Create a session for validating an email address.
The identity server will send an email containing a token. If that
token is presented to the identity server in the future, it indicates
that that user was able to read the email for that email address, and
so we validate ownership of the email address.
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
`/register/email/requestToken` is designed specifically for use when
registering an account and therefore will inform the user if the email
address given is already registered on the server.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailRequestToken
deprecated: true
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are:
- `M_INVALID_EMAIL`: The email address provided was invalid.
- `M_EMAIL_SEND_ERROR`: The validation email could not be sent.
examples:
application/json: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken":
post:
summary: Validate ownership of an email address.
description: |-
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
normalisation. Whether to do so is an implementation detail for the
identity server. Clients must always pass on the token without
modification.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPost
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and emailed to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of an email address.
description: |-
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
`requestToken` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: emailSubmitTokenGet
deprecated: true
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
- in: query
type: string
name: token
required: true
description: The token generated by the `requestToken` call and emailed to the user.
x-example: atoken
responses:
200:
description: Email address is validated.
"3xx":
description: |-
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.

97
data/api/identity/invitation_signing.yaml
View file

@ -1,97 +0,0 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Ephemeral Invitation Signing API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/sign-ed25519":
post:
summary: Sign invitation details
description: |-
Sign invitation details.
The identity server will look up `token` which was stored in a call
to `store-invite`, and fetch the sender of the invite.
operationId: blindlySignStuff
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
required: ["mxid", "token", "private_key"]
responses:
200:
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
type: object
description: The signature of the mxid, sender, and token.
$ref: "../../schemas/server-signatures.yaml"
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
404:
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

171
data/api/identity/lookup.yaml
View file

@ -1,171 +0,0 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Lookup API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/lookup":
get:
summary: Look up the Matrix user ID for a 3pid.
description: Look up the Matrix user ID for a 3pid.
operationId: lookupUser
deprecated: true
parameters:
- in: query
type: string
name: medium
required: true
description: The medium type of the 3pid. See the [3PID Types](/appendices/#3pid-types) Appendix.
x-example: "email"
- in: query
type: string
name: address
required: true
description: The address of the 3pid being looked up. See the [3PID Types](/appendices/#3pid-types) Appendix.
x-example: "louise@bobs.burgers"
responses:
200:
description:
The association for that 3pid, or an empty object if no association is known.
examples:
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up, matching the address requested.
medium:
type: string
description: A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium requested.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
description: A unix timestamp before which the association is not known to be valid.
not_after:
type: integer
description: A unix timestamp after which the association is not known to be valid.
ts:
type: integer
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers.
$ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
"/bulk_lookup":
post:
summary: Lookup Matrix user IDs for a list of 3pids.
description: Lookup Matrix user IDs for a list of 3pids.
operationId: lookupUsers
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"threepids":
[
["email","user@example.org"],
["msisdn", "123456789"],
["email","user2@example.org"]
]
}
properties:
threepids:
type: array
items:
type: array
title: 3PID mappings
minItems: 2
maxItems: 2
items:
# TODO: Give real names to these values. Adding a `title` does not work.
#- type: 3PID Medium
#- type: 3PID Address
- type: string
- type: string
description: |-
An array of arrays containing the [3PID Types](/appendices/#3pid-types) with the `medium`
in first position and the `address` in second position.
required:
- "threepids"
responses:
200:
description: A list of known 3PID mappings for the supplied 3PIDs.
examples:
application/json: {
"threepids": [
["email","user@example.org", "@bla:example.org"],
["msisdn", "123456789", "@blah2:example.com"]
]
}
schema:
type: object
properties:
threepids:
type: array
items:
type: array
title: 3PID mappings
minItems: 3
maxItems: 3
items:
# TODO: Give real names to these values. Adding a `title` does not work.
#- type: 3PID Medium
#- type: 3PID Address
#- type: Matrix User ID
- type: string
- type: string
- type: string
description: |-
An array of array containing the [3PID Types](/appendices/#3pid-types) with the `medium`
in first position, the `address` in second position and Matrix user
ID in third position.
required:
- "threepids"

179
data/api/identity/phone_associations.yaml
View file

@ -1,179 +0,0 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Phone Number Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/validate/msisdn/requestToken":
post:
summary: Request a token for validating a phone number.
description: |-
Create a session for validating a phone number.
The identity server will send an SMS message containing a token. If
that token is presented to the identity server in the future, it
indicates that that user was able to read the SMS for that phone
number, and so we validate ownership of the phone number.
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
`/register/msisdn/requestToken` is designed specifically for use when
registering an account and therefore will inform the user if the phone
number given is already registered on the server.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestToken
deprecated: true
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are:
- `M_INVALID_ADDRESS`: The phone number provided was invalid.
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken":
post:
summary: Validate ownership of a phone number.
description: |-
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
`requestToken` call, ownership of the phone number is considered to
have been validated. This does not publish any information publicly, or
associate the phone number address with any Matrix user
ID. Specifically, calls to `/lookup` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
normalisation. Whether to do so is an implementation detail for the
identity server. Clients must always pass on the token without
modification.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPost
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and sent to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of a phone number.
description: |-
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
`requestToken` call, ownership of the phone number address is
considered to have been validated. This does not publish any
information publicly, or associate the phone number with any Matrix
user ID. Specifically, calls to `/lookup` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: msisdnSubmitTokenGet
deprecated: true
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
- in: query
type: string
name: token
required: true
description: The token generated by the `requestToken` call and sent to the user.
x-example: atoken
responses:
200:
description: Phone number is validated.
"3xx":
description: |-
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.

46
data/api/identity/ping.yaml
View file

@ -1,46 +0,0 @@
# Copyright 2018 Kamax Sàrl
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: "2.0"
info:
title: "Matrix Identity Service Ping API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
paths:
"/api/v1":
get:
summary: Checks that an identity server is available at this API endpoint.
description: |-
Checks that an identity server is available at this API endpoint.
To discover that an identity server is available at a specific URL,
this endpoint can be queried and will return an empty object.
This is primarly used for auto-discovery and health check purposes
by entities acting as a client for the identity server.
operationId: ping
deprecated: true
responses:
200:
description: An identity server is ready to serve requests.
examples:
application/json: {}
schema:
type: object

129
data/api/identity/pubkey.yaml
View file

@ -1,129 +0,0 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Public Key API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/pubkey/{keyId}":
get:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
operationId: getPubKey
deprecated: true
parameters:
- in: path
type: string
name: keyId
required: true
description: |-
The ID of the key. This should take the form algorithm:identifier
where algorithm identifies the signing algorithm, and the identifier
is an opaque string.
x-example: "ed25519:0"
responses:
200:
description:
The public key exists.
examples:
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
schema:
type: object
properties:
public_key:
type: string
description: Unpadded Base64 encoded public key.
required: ['public_key']
404:
description:
The public key was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid":
get:
summary: Check whether a long-term public key is valid.
description: |-
Check whether a long-term public key is valid. The response should always
be the same, provided the key exists.
operationId: isPubKeyValid
deprecated: true
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
get:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValid
deprecated: true
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']

161
data/api/identity/store_invite.yaml
View file

@ -1,161 +0,0 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Store Invitations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/store-invite":
post:
summary: Store pending invitations to a user's 3pid.
description: |-
Store pending invitations to a user's 3pid.
In addition to the request parameters specified below, an arbitrary
number of other parameters may also be specified. These may be used in
the invite message generation described below.
The service will generate a random token and an ephemeral key used for
accepting the invite.
The service also generates a `display_name` for the inviter, which is
a redacted version of `address` which does not leak the full contents
of the `address`.
The service records persistently all of the above information.
It also generates an email containing all of this data, sent to the
`address` parameter, notifying them of the invitation.
Also, the generated ephemeral public key will be listed as valid on
requests to `/_matrix/identity/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
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the `m.room.avatar` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
required: ["medium", "address", "room_id", "sender"]
responses:
200:
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: string
display_name:
type: string
description: The generated (redacted) display_name.
required: ['token', 'public_keys', 'display_name']
example:
application/json: {
"token": "sometoken",
"public_keys": [
"serverpublickey",
"ephemeralpublickey"
],
"display_name": "f...@b..."
}
400:
description: |
An error has occured.
If the 3pid is already bound to a Matrix user ID, the error code
will be `M_THREEPID_IN_USE`. If the medium is unsupported, the
error code will be `M_UNRECOGNIZED`.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

6
package-lock.json generated
View file

@ -539,9 +539,9 @@
} }
}, },
"lodash": { "lodash": {
"version": "4.17.20", "version": "4.17.21",
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
"integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA==", "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
"dev": true "dev": true
}, },
"log-symbols": { "log-symbols": {

427
proposals/1772-groups-as-rooms.md Normal file
View file

@ -0,0 +1,427 @@
# Proposal for Matrix "spaces" (formerly known as "groups as rooms (take 2)")
This MSC, and related proposals, supercede
[MSC1215](https://github.com/matrix-org/matrix-doc/issues/1215).
## Background and objectives
Collecting rooms together into groups is useful for a number of
purposes. Examples include:
* Allowing users to discover different rooms related to a particular topic:
for example "official matrix.org rooms".
* Allowing administrators to manage permissions across a number of rooms: for
example "a new employee has joined my company and needs access to all of our
rooms".
* Letting users classify their rooms: for example, separating "work" from
"personal" rooms.
We refer to such collections of rooms as "spaces".
Synapse and Element-Web currently implement an unspecced "groups" API (referred
to as "`/r0/groups`" in this document) which attempts to provide this
functionality (see
[MSC971](https://github.com/matrix-org/matrix-doc/issues/971)). However,
this is a complex API which has various problems (see
[appendix](#appendix-problems-with-the-r0groups-api)).
This proposal suggests a new approach where spaces are themselves represented
by rooms, rather than a custom first-class entity. This requires minimal
server changes.
The existing `/r0/groups` API would be deprecated in Synapse and remain
unspecified.
## Proposal
Each space is represented by its own room, known as a "space-room". The rooms
within the space are determined by state events within the space-room.
Space-rooms are distinguished from regular messaging rooms by the presence of
a `'type': 'm.space'` property in the content of the `m.room.create` event.
The value of the `type` property uses the Standardised Identifier Grammar from
[MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758). This allows clients to offer slightly customised user experience
depending on the purpose of the room. Currently, no server-side behaviour is
expected to depend on this property. A `type` property on the `m.room.create`
event is used to ensure that a room cannot change between being a space-room
and a non-space room. For more information, see the "Rejected Alternatives"
section below. Additionally, no client behaviour is recommended for handling
unknown room types given the potential for legacy data: clients are free to
make their own decisions about hiding unknown room types from users, though
should note that a future conversation-like type (for example) might be
introduced and could be considered "unknown" by older versions of their client.
As with regular rooms, public spaces are expected to have an alias, for example
`#foo:matrix.org`, which can be used to refer to the space.
Space-rooms may have `m.room.name`, `m.room.avatar` and `m.room.topic` state
events in the same way as a normal room.
Normal messages within a space-room are discouraged (but not blocked by the
server): user interfaces are not expected to have a way to enter or display
such messages. Space-rooms should be created with a power level for
`events_default` of 100, to prevent the rooms accidentally/maliciously
clogging up with messages from random members of the space.
### Membership of spaces
Users can be members of spaces (represented by `m.room.member` state events as
normal). The existing [`m.room.history_visibility`
mechanism](https://matrix.org/docs/spec/client_server/r0.6.1#room-history-visibility)
controls whether membership of the space is required to view the room list,
membership list, etc. "Public" or "community" spaces would be set to
`world_readable` to allow clients to see the directory of rooms within the
space by peeking into the space-room (thus avoiding the need to add
`m.room.member` events to the event graph within the room).
Join rules, invites and 3PID invites work as for a normal room. In order for
clients to distinguish space invites from room invites, all invites must now
include the `m.room.create` event in their `invite_state` and `knock_state`.
### Relationship between rooms and spaces
The intention is that rooms and spaces form a hierarchy, which clients can use
to structure the user's room list into a tree view. The parent/child
relationship can be expressed in one of two ways:
1. The admins of a space can advertise rooms and subspaces for their space by
setting `m.space.child` state events. The `state_key` is the ID of a child
room or space, and the content must contain a `via` key which gives a list
of candidate servers that can be used to join the room. Something like:
```jsonc
// a child room
{
"type": "m.space.child",
"state_key": "!abcd:example.com",
"content": {
"via": ["example.com", "test.org"]
}
}
// a child room with an ordering.
{
"type": "m.space.child",
"state_key": "!efgh:example.com",
"content": {
"via": ["example.com"],
"order": "abcd"
}
}
// no longer a child room
{
"type": "m.space.child",
"state_key": "!jklm:example.com",
"content": {}
}
```
Children where `via` is not present or invalid (not an array) are ignored.
The `order` key is a string which is used to provide a default ordering of
siblings in the room list. (Rooms are sorted based on a lexicographic
ordering of the Unicode codepoints of the characters in `order` values.
Rooms with no `order` come last, in ascending numeric order of the
`origin_server_ts` of their `m.room.create` events, or ascending
lexicographic order of their `room_id`s in case of equal
`origin_server_ts`. `order`s which are not strings, or do not consist
solely of ascii characters in the range `\x20` (space) to `\x7E` (`~`), or
consist of more than 50 characters, are forbidden and the field should be
ignored if received.)
2. Separately, rooms can claim parents via the `m.space.parent` state
event.
Similar to `m.space.child`, the `state_key` is the ID of the parent space,
and the content must contain a `via` key which gives a list of candidate
servers that can be used to join the parent.
```jsonc
{
"type": "m.space.parent",
"state_key": "!space:example.com",
"content": {
"via": ["example.com"],
"canonical": true
}
}
```
Parents where `via` is not present or invalid (not an array) are ignored.
`canonical` determines whether this is the main parent for the space. When
a user joins a room with a canonical parent, clients may switch to view the
room in the context of that space, peeking into it in order to find other
rooms and group them together. In practice, well behaved rooms should only
have one `canonical` parent, but given this is not enforced: if multiple
are present the client should select the one with the lowest room ID, as
determined via a lexicographic ordering of the Unicode code-points.
To avoid abuse where a room admin falsely claims that a room is part of a
space that it should not be, clients could ignore such `m.space.parent`
events unless either (a) there is a corresponding `m.space.child` event in
the claimed parent, or (b) the sender of the `m.space.child` event has a
sufficient power-level to send such an `m.space.child` event in the
parent. (It is not necessarily required that that user currently be a
member of the parent room - only the `m.room.power_levels` event is
inspected.) [Checking the power-level rather than requiring an *actual*
`m.space.child` event in the parent allows for "secret" rooms (see below).]
Where the parent space also claims a parent, clients can recursively peek
into the grandparent space, and so on.
This structure means that rooms can end up appearing multiple times in the
room list hierarchy, given they can be children of multiple different spaces
(or have multiple parents in different spaces).
In a typical hierarchy, we expect *both* parent->child and child->parent
relationships to exist, so that the space can be discovered from the room, and
vice versa. Occasions when the relationship only exists in one direction
include:
* User-curated lists of rooms: in this case the space will not be listed as a
parent of the room.
* "Secret" rooms: rooms where the admin does not want the room to be
advertised as part of a given space, but *does* want the room to form part
of the hierarchy of that space for those in the know.
Cycles in the parent->child and child->parent relationships are *not*
permitted, but clients (and servers) should be aware that they may be
encountered, and MUST spot and break cycles rather than infinitely looping.
### Suggested children
Space admins can mark particular children of a space as "suggested". This
mainly serves as a hint to clients that that they can be displayed differently
(for example by showing them eagerly in the room list), though future
server-side interfaces (such as the summary API proposed in
[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) might also
make use of it.
A suggested child is identified by a `"suggested": true` property in the
`m.space.child` event:
```jsonc
{
"type": "m.space.child",
"state_key": "!abcd:example.com",
"content": {
"via": ["example.com", "test.org"],
"suggested": true
}
}
```
A child which is missing the `suggested` property is treated identically to a
child with `"suggested": false`. A suggested child may be a room or a subspace.
### Extended "room invite state"
The specification is currently vague about what room state should be available
to users that have been invited to a room, though the Federation API spec does
recommend that the `invite_room_state` sent over federation via [PUT
`/_matrix/federation/v2/invite`](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid)
should include "the join rules, canonical alias, avatar, and name of the room".
This MSC proposes adding `m.room.create` to that list, so that the recipient of
an invite can distinguish invites to spaces from other invites.
## Future extensions
The following sections are not blocking parts of this proposal, but are
included as a useful reference for how we imagine it will be extended in future.
### Auto-joined children
We could add an `auto_join` flag to `m.space.child` events to allow a space
admin to list the sub-spaces and rooms in that space which should be
automatically joined by members of that space.
This would be distinct from a force-join: the user could subsequently part any
auto-joined room if they desire.
Joining would be performed by the client. This could possibly be sped up by
using a summary API (such as that proposed in
[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) to get a summary
of the spacetree to be joined, and then using a batch join API to join
whichever subset of it makes most sense for the client's UX.
Obviously auto-joining can be a DoS vector, and we consider it to be antisocial
for a space to try to autojoin its members to more than 100 children (in total).
Clients could display the auto-joined children in the room list whenever the
space appears in the list - thus helping users discover other rooms in a space
even if they're not joined to that space. For instance, if you join
`#matrix:matrix.org`, your client could show that room in the context of its
parent space, with that space's auto-joined children shown alongside it as
siblings.
### Restricting access to the spaces membership list
In the existing `/r0/groups` API, the group server has total control over the
visibility of group membership, as seen by a given querying user. In other
words, arbitrary users can see entirely different views of a group at the
server's discretion.
Whilst this is very powerful for mapping arbitrary organisational structures
into Matrix, it may be overengineered. Instead, the common case is (we believe)
a space where some users are publicly visible as members, and others are not.
One way of achieving this would be to create a separate space for the
private members - e.g. have `#foo:matrix.org` and `#foo-private:matrix.org`.
`#foo-private:matrix.org` is set up with `m.room.history_visibility` to not to
allow peeking; you have to be joined to see the members.
It's worth noting that any member of a space can currently see who else is a
member of that space, which might pose privacy problems for sensitive spaces.
While the server itself will inevitably track the space membership in state
events, a future MSC could restrict the membership from being sent to clients.
This is essentially the same as
[matrix-doc#1653](https://github.com/matrix-org/matrix-doc/issues/1653).
### Flair
("Flair" is a term we use to describe a small badge which appears next to a
user's displayname to advertise their membership of a space.)
The flair image for a group is given by the room avatar. (In future it might
preferable to use hand-crafted small resolution images: see
[matrix-doc#1778](https://github.com/matrix-org/matrix-doc/issues/1778).
One way this might be implemented is:
* User publishes the spaces they wish to announce on their profile
([MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769)
as an `m.flair` state event: it lists the spaces which they are advertising.
* When a client wants to know the current flair for a set of users (i.e.
those which it is currently displaying in the timeline), it peeks the
profile rooms of those users. (Ideally there would be an API to support
peeking multiple rooms at once to facilitate this.)
* The client must check that the user is *actually* a member of the advertised
spaces. Nominally it can do this by peeking the membership list of the
space; however for efficiency we could expose a dedicated Client-Server API
to do this check (and both servers and clients can cache the results fairly
aggressively.)
## Related MSCs
* [MSC2946](https://github.com/matrix-org/matrix-doc/issues/2946): Spaces
Summary API.
* [MSC2962](https://github.com/matrix-org/matrix-doc/issues/2962): Managing
power levels via Spaces.
* [MSC3083](https://github.com/matrix-org/matrix-doc/issues/3083): Restricting
room membership based on space membership.
* [MSC2753](https://github.com/matrix-org/matrix-doc/issues/2753) for
effective peeking over the C/S API.
* [MSC2444](https://github.com/matrix-org/matrix-doc/issues/2444) (or similar)
for effective peeking over Federation.
## Security considerations
None at present.
## Potential issues
* If the membership of a space would be large (for example: an organisation of
several thousand people), this membership has to be copied entirely into the
room, rather than querying/searching incrementally.
* If the membership list is based on an external service such as LDAP, it is
hard to keep the space membership in sync with the LDAP directory. In
practice, it might be possible to do so via a nightly "synchronisation" job
which searches the LDAP directory, or via "AD auditing".
* No allowance is made for exposing different 'views' of the membership list to
different querying users. (It may be possible to simulate this behaviour
using smaller spaces).
* The requirement that `m.space.parent` links be ignored unless the sender has a
high PL in the parent room could lead to suprising effects where a parent
link suddenly ceases to take effect because a user loses their PL in the
parent room. This is mitigated in the general case by honouring the parent
link when there is a corresponding `m.space.child` event, however it remains
a problem for "secret" rooms.
* The `via` servers listed in the `m.space.child` and `m.space.parent` events
could get out of date, and will need to be updated from time to time. This
remains an unsolved problem.
## Rejected alternatives
### Use a separate state event for type of room
[MSC1840](https://github.com/matrix-org/matrix-doc/pull/1840) proposes the use
of a separate `m.room.type` state event to distinguish different room types.
This implies that rooms can dynamically switch between being a Space, and
being a regular non-Space room. That is not a usecase we consider useful, and
allowing it would impose significant complexity on client and server
implementations. Specifically, client and server implementations who store
spaces separately from rooms would have to support migrating back and forth
between them and dealing with the ambiguities of `room_id`s no longer pointing
to valid spaces, etc.
### Use a different sigil/twigil for spaces
Groups used + as a sigil to differentiate them from rooms (e.g. +matrix:matrix.org).
We considered doing similar for Spaces, e.g. a #+ twigil or reuse the + sigil,
but concluded that the resulting complexity and exoticism is not worth it.
This means that clients such as matrix.to have to peek into rooms to find out their
`type` before being able to display an appropriate UI, and users will not know
whether #matrix:matrix.org is a room or a space without using a client (e.g. if
reading an advert). It also means that if the client UI requires a space alias the
client will need to validate the entered data serverside.
## Unstable prefix
The following mapping will be used for identifiers in this MSC during
development:
Proposed final identifier | Purpose | Development identifier
------------------------------- | ------- | ----
`type` | property in `m.room.create` | `org.matrix.msc1772.type`
`m.space` | value of `type` in `m.room.create` | `org.matrix.msc1772.space`
`m.space.child` | event type | `org.matrix.msc1772.space.child`
`m.space.parent` | event type | `org.matrix.msc1772.space.parent`
## History
* This replaces [MSC1215](https://docs.google.com/document/d/1ZnAuA_zti-K2-RnheXII1F1-oyVziT4tJffdw1-SHrE).
* Other thoughts that led into this are [documented](https://docs.google.com/document/d/1hljmD-ytdCRL37t-D_LvGDA3a0_2MwowSPIiZRxcabs).
## Appendix: problems with the `/r0/groups` API
The existing `/r0/groups` API, as proposed in
[MSC971](https://github.com/matrix-org/matrix-doc/issues/971), has various
problems, including:
* It is a large API surface to implement, maintain and spec - particularly for
all the different clients out there.
* Much of the API overlaps significantly with mechanisms we already have for
managing rooms:
* Tracking membership identity
* Tracking membership hierarchy
* Inviting/kicking/banning user
* Tracking key/value metadata
* There are membership management features which could benefit rooms which
would also benefit groups and vice versa (e.g. "auditorium mode")
* The current implementations on Riot Web/iOS/Android all suffer bugs and
issues which have been solved previously for rooms.
* no local-echo of invites
* failures to set group avatars
* ability to specify multiple admins
* It doesn't support pushing updates to clients (particularly for flair
membership): https://github.com/vector-im/riot-web/issues/5235
* It doesn't support third-party invites.
* Groups could benefit from other features which already exist today for rooms
* e.g. Room Directories
* Groups are centralised, rather than being replicated across all
participating servers.

40
proposals/3122-deprecate-starting-verifications-without-request.md Normal file
View file

@ -0,0 +1,40 @@
# MSC3122: Deprecate starting key verifications without requesting first
Currently, the [Key verification
framework](https://spec.matrix.org/unstable/client-server-api/#key-verification-framework)
allows a device to begin a verification via to-device messages by sending an
`m.key.verification.start` event without first sending or receiving an
`m.key.verification.request` message. (The last sentence of the 5th paragraph
of the Key verification framework in the unstable spec, as of the time of
writing.) However, doing so does not provide a good user experience, and
allowing this adds unnecessary complexity to implementations.
We propose to deprecate allowing this behaviour.
Note that verifications in DMs do not allow this behaviour. Currently, Element
Web is the only client known to do this.
## Proposal
The ability to begin a key verification by sending an
`m.key.verification.start` event as a to-device event without a prior
`m.key.verification.request` is deprecated. New clients should not begin
verifications in this way, but will still need to accept verifications begun in
this way, until it is removed from the spec.
## Potential issues
None.
## Alternatives
We could do nothing and leave it in the spec. But we should clean up cruft when
possible.
## Security considerations
None.
## Unstable prefix
No unstable prefix is required since we are simply deprecating behaviour.