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

Change RST code formatting markup to Markdown

Browse source
This commit is contained in:
Will 2021-01-27 12:14:31 -08:00 • committed by Richard van der Hoff
parent c7cf90abfa
commit 27f8867aa0
158 changed files with 931 additions and 931 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -35,13 +35,13 @@ paths:
- in: query
type: string
name: sid
description: The Session ID generated by the ``requestToken`` call.
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.
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
@ -72,9 +72,9 @@ paths:
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``.
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",
@ -97,12 +97,12 @@ paths:
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
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: bind
deprecated: true
@ -119,10 +119,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
@ -184,9 +184,9 @@ paths:
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``.
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",
@ -209,15 +209,15 @@ paths:
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
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.
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
@ -241,10 +241,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
@ -253,7 +253,7 @@ paths:
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.
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string

6
data/api/identity/definitions/request_email_validation.yaml
View file

@ -23,7 +23,7 @@ properties:
description: |
A unique string generated by the client, and used to identify the
validation attempt. It must be a string consisting of the characters
``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it
must not be empty.
example: "monkeys_are_GREAT"
email:
@ -33,9 +33,9 @@ properties:
send_attempt:
type: integer
description: |-
The server will only send an email if the ``send_attempt``
The server will only send an email if the `send_attempt`
is a number greater than the most recent one which it has seen,
scoped to that ``email`` + ``client_secret`` pair. This is to
scoped to that `email` + `client_secret` pair. This is to
avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity server.
The client should increment this value if they desire a new

8
data/api/identity/definitions/request_msisdn_validation.yaml
View file

@ -24,14 +24,14 @@ properties:
description: |
A unique string generated by the client, and used to identify the
validation attempt. It must be a string consisting of the characters
``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it
must not be empty.
example: "monkeys_are_GREAT"
country:
type: string
description: |-
The two-letter uppercase ISO-3166-1 alpha-2 country code that the
number in ``phone_number`` should be parsed as if it were dialled from.
number in `phone_number` should be parsed as if it were dialled from.
example: "GB"
phone_number:
type: string
@ -40,9 +40,9 @@ properties:
send_attempt:
type: integer
description: |-
The server will only send an SMS if the ``send_attempt`` is a
The server will only send an SMS if the `send_attempt` is a
number greater than the most recent one which it has seen,
scoped to that ``country`` + ``phone_number`` + ``client_secret``
scoped to that `country` + `phone_number` + `client_secret`
triple. This is to avoid repeatedly sending the same SMS in
the case of request retries between the POSTing user and the
identity server. The client should increment this value if

2
data/api/identity/definitions/security.yaml
View file

@ -13,6 +13,6 @@
# limitations under the License.
accessToken:
type: apiKey
description: The access_token returned by a call to ``/register``.
description: The access_token returned by a call to `/register`.
name: access_token
in: query

2
data/api/identity/definitions/sid.yaml
View file

@ -18,7 +18,7 @@ properties:
description: |
The session ID. Session IDs are opaque strings generated by the identity
server. They must consist entirely of the characters
``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they
`[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they
must not be empty.
example: "123abc"
required: ['sid']

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

@ -37,13 +37,13 @@ paths:
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
`/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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailRequestToken
deprecated: true
@ -61,8 +61,8 @@ paths:
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.
- `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",
@ -77,10 +77,10 @@ paths:
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
`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.
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
@ -90,7 +90,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPost
deprecated: true
@ -107,13 +107,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
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.
description: The token generated by the `requestToken` call and emailed to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -136,10 +136,10 @@ paths:
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
`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.
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.
@ -150,28 +150,28 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
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.
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.
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.
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.

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

@ -30,8 +30,8 @@ paths:
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.
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:
@ -50,7 +50,7 @@ paths:
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to ``store-invite``.
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.

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

@ -131,8 +131,8 @@ paths:
- type: string
- type: string
description: |-
An array of arrays containing the `3PID Types`_ with the ``medium``
in first position and the ``address`` in second position.
An array of arrays containing the `3PID Types`_ with the `medium`
in first position and the `address` in second position.
required:
- "threepids"
responses:
@ -164,8 +164,8 @@ paths:
- type: string
- type: string
description: |-
An array of array containing the `3PID Types`_ with the ``medium``
in first position, the ``address`` in second position and Matrix user
An array of array containing the `3PID Types`_ with the `medium`
in first position, the `address` in second position and Matrix user
ID in third position.
required:
- "threepids"

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

@ -37,13 +37,13 @@ paths:
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
`/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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestToken
deprecated: true
@ -61,9 +61,9 @@ paths:
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
- `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: {
@ -79,10 +79,10 @@ paths:
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
`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.
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
@ -92,7 +92,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPost
deprecated: true
@ -109,13 +109,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
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.
description: The token generated by the `requestToken` call and sent to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -138,10 +138,10 @@ paths:
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
`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.
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.
@ -152,28 +152,28 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
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.
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.
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.
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.

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

@ -37,23 +37,23 @@ paths:
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 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.
`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``.
requests to `/_matrix/identity/api/v1/pubkey/ephemeral/isvalid`.
Currently, invites may only be issued for 3pids of the ``email`` medium.
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.
the `address` of the pending invite for display purposes.
operationId: storeInvite
deprecated: true
parameters:
@ -64,7 +64,7 @@ paths:
properties:
medium:
type: string
description: The literal string ``email``.
description: The literal string `email`.
example: "email"
address:
type: string
@ -82,26 +82,26 @@ paths:
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``
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.
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.
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.
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
@ -122,7 +122,7 @@ paths:
type: string
description: |
The generated token. Must be a string consisting of the
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
@ -149,8 +149,8 @@ paths:
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``.
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",

44
data/api/identity/v2_associations.yaml
View file

@ -39,13 +39,13 @@ paths:
- in: query
type: string
name: sid
description: The Session ID generated by the ``requestToken`` call.
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.
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
@ -76,9 +76,9 @@ paths:
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``.
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",
@ -98,7 +98,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -112,12 +112,12 @@ paths:
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
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: bindV2
security:
@ -135,10 +135,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
@ -200,9 +200,9 @@ paths:
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``.
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",
@ -222,7 +222,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -236,15 +236,15 @@ paths:
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
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.
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
@ -269,10 +269,10 @@ paths:
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
@ -281,7 +281,7 @@ paths:
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.
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
@ -317,7 +317,7 @@ paths:
the chosen authentication method (such as blocking homeservers from
unbinding identifiers).
Another common error code is ``M_TERMS_NOT_SIGNED`` where the user
Another common error code is `M_TERMS_NOT_SIGNED` where the user
needs to `agree to more terms`_ in order to continue.
examples:
application/json: {

6
data/api/identity/v2_auth.yaml
View file

@ -32,7 +32,7 @@ paths:
description: |-
Exchanges an OpenID token from the homeserver for an access token to
access the identity server. The request body is the same as the values
returned by ``/openid/request_token`` in the Client-Server API.
returned by `/openid/request_token` in the Client-Server API.
operationId: registerAccount
parameters:
- in: body
@ -83,7 +83,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -121,7 +121,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

42
data/api/identity/v2_email_associations.yaml
View file

@ -40,13 +40,13 @@ paths:
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
`/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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailRequestTokenV2
security:
@ -65,8 +65,8 @@ paths:
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.
- `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",
@ -77,7 +77,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -92,10 +92,10 @@ paths:
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
`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.
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
@ -105,7 +105,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPostV2
security:
@ -123,13 +123,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
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.
description: The token generated by the `requestToken` call and emailed to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -149,7 +149,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -163,10 +163,10 @@ paths:
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
`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.
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.
@ -178,35 +178,35 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
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.
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.
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.
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

8
data/api/identity/v2_invitation_signing.yaml
View file

@ -33,8 +33,8 @@ paths:
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.
The identity server will look up `token` which was stored in a call
to `store-invite`, and fetch the sender of the invite.
operationId: blindlySignStuffV2
security:
- accessToken: []
@ -54,7 +54,7 @@ paths:
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to ``store-invite``.
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.
@ -102,7 +102,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

28
data/api/identity/v2_lookup.yaml
View file

@ -55,7 +55,7 @@ paths:
type: string
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the ``/lookup`` endpoint when performing lookups.
supply to the `/lookup` endpoint when performing lookups.
Servers SHOULD rotate this string often.
algorithms:
@ -63,7 +63,7 @@ paths:
items:
type: string
description: |-
The algorithms the server supports. Must contain at least ``sha256``.
The algorithms the server supports. Must contain at least `sha256`.
required: ['lookup_pepper', 'algorithms']
"/lookup":
post:
@ -84,14 +84,14 @@ paths:
algorithm:
type: string
description: |-
The algorithm the client is using to encode the ``addresses``. This
should be one of the available options from ``/hash_details``.
The algorithm the client is using to encode the `addresses`. This
should be one of the available options from `/hash_details`.
example: "sha256"
pepper:
type: string
description: |-
The pepper from ``/hash_details``. This is required even when the
``algorithm`` does not make use of it.
The pepper from `/hash_details`. This is required even when the
`algorithm` does not make use of it.
example: "matrixrocks"
addresses:
type: array
@ -99,7 +99,7 @@ paths:
type: string
description: |-
The addresses to look up. The format of the entries here depend on
the ``algorithm`` used. Note that queries which have been incorrectly
the `algorithm` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
example: [
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
@ -109,7 +109,7 @@ paths:
responses:
200:
description:
The associations for any matched ``addresses``.
The associations for any matched `addresses`.
examples:
application/json: {
"mappings": {
@ -122,7 +122,7 @@ paths:
mappings:
type: object
description: |-
Any applicable mappings of ``addresses`` to Matrix User IDs. Addresses
Any applicable mappings of `addresses` to Matrix User IDs. Addresses
which do not have associations will not be included, which can make
this property be an empty object.
title: AssociatedMappings
@ -132,13 +132,13 @@ paths:
400:
description:
The client's request was invalid in some way. One possible problem could
be the ``pepper`` being invalid after the server has rotated it - this is
presented with the ``M_INVALID_PEPPER`` error code. Clients SHOULD make
a call to ``/hash_details`` to get a new pepper in this scenario, being
be the `pepper` being invalid after the server has rotated it - this is
presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make
a call to `/hash_details` to get a new pepper in this scenario, being
careful to avoid retry loops.
``M_INVALID_PARAM`` can also be returned to indicate the client supplied
an ``algorithm`` that is unknown to the server.
`M_INVALID_PARAM` can also be returned to indicate the client supplied
an `algorithm` that is unknown to the server.
examples:
application/json: {
"errcode": "M_INVALID_PEPPER",

44
data/api/identity/v2_phone_associations.yaml
View file

@ -40,13 +40,13 @@ paths:
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
`/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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnRequestTokenV2
security:
@ -65,9 +65,9 @@ paths:
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
- `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: {
@ -79,7 +79,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -94,10 +94,10 @@ paths:
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
`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.
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
@ -107,7 +107,7 @@ paths:
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
`application/x-form-www-urlencoded` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPostV2
security:
@ -125,13 +125,13 @@ paths:
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
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.
description: The token generated by the `requestToken` call and sent to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
@ -151,7 +151,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
@ -165,10 +165,10 @@ paths:
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
`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.
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.
@ -180,35 +180,35 @@ paths:
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
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.
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.
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.
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

34
data/api/identity/v2_store_invite.yaml
View file

@ -40,23 +40,23 @@ paths:
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 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.
`address` parameter, notifying them of the invitation.
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``.
requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
Currently, invites may only be issued for 3pids of the ``email`` medium.
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.
the `address` of the pending invite for display purposes.
operationId: storeInviteV2
security:
- accessToken: []
@ -68,7 +68,7 @@ paths:
properties:
medium:
type: string
description: The literal string ``email``.
description: The literal string `email`.
example: "email"
address:
type: string
@ -86,26 +86,26 @@ paths:
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``
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.
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.
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.
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
@ -126,7 +126,7 @@ paths:
type: string
description: |
The generated token. Must be a string consisting of the
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
@ -153,8 +153,8 @@ paths:
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``.
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",
@ -166,7 +166,7 @@ paths:
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",

4
data/api/identity/v2_terms.yaml
View file

@ -106,7 +106,7 @@ paths:
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the ``m.accepted_terms`` collection.
have already added that URL to the `m.accepted_terms` collection.
required: ['name', 'url']
required: ['policies']
post:
@ -121,7 +121,7 @@ paths:
to the user. Servers SHOULD consider acceptance of any one language's URL as
acceptance for all other languages of that policy.
The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client
The server should avoid returning `M_TERMS_NOT_SIGNED` because the client
may not be accepting all terms at once.
operationId: agreeToTerms
security: