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

96
data/api/client-server/registration.yaml
View file

@ -43,27 +43,27 @@ paths:
If registration is successful, this endpoint will issue an access token
the client can use to authorize itself in subsequent requests.
If the client does not supply a ``device_id``, the server must
If the client does not supply a `device_id`, the server must
auto-generate one.
The server SHOULD register an account with a User ID based on the
``username`` provided, if any. Note that the grammar of Matrix User ID
`username` provided, if any. Note that the grammar of Matrix User ID
localparts is restricted, so the server MUST either map the provided
``username`` onto a ``user_id`` in a logical manner, or reject
``username``\s which do not comply to the grammar, with
``M_INVALID_USERNAME``.
`username` onto a `user_id` in a logical manner, or reject
`username`\s which do not comply to the grammar, with
`M_INVALID_USERNAME`.
Matrix clients MUST NOT assume that localpart of the registered
``user_id`` matches the provided ``username``.
`user_id` matches the provided `username`.
The returned access token must be associated with the ``device_id``
The returned access token must be associated with the `device_id`
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
When registering a guest account, all parameters in the request body
with the exception of ``initial_device_display_name`` MUST BE ignored
by the server. The server MUST pick a ``device_id`` for the account
with the exception of `initial_device_display_name` MUST BE ignored
by the server. The server MUST pick a `device_id` for the account
regardless of input.
Any user ID returned by this API must conform to the grammar given in the
@ -81,7 +81,7 @@ paths:
enum:
- guest
- user
description: The kind of account to register. Defaults to ``user``.
description: The kind of account to register. Defaults to `user`.
- in: body
name: body
required: true
@ -94,7 +94,7 @@ paths:
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself.
authenticate the `register` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
@ -118,12 +118,12 @@ paths:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if ``device_id`` corresponds to a known device.
if `device_id` corresponds to a known device.
example: Jungle Phone
inhibit_login:
type: boolean
description: |-
If true, an ``access_token`` and ``device_id`` should not be
If true, an `access_token` and `device_id` should not be
returned from this call, therefore preventing an automatic
login. Defaults to false.
example: false
@ -151,7 +151,7 @@ paths:
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
Required if the ``inhibit_login`` option is false.
Required if the `inhibit_login` option is false.
home_server:
type: string
description: |-
@ -159,22 +159,22 @@ paths:
been registered.
**Deprecated**. Clients should extract the server_name from
``user_id`` (by splitting at the first colon) if they require
it. Note also that ``homeserver`` is not spelt this way.
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
ID of the registered device. Will be the same as the
corresponding parameter in the request, if one was specified.
Required if the ``inhibit_login`` option is false.
Required if the `inhibit_login` option is false.
required: ['user_id']
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_USER_IN_USE`` : The desired user ID is already taken.
* ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name.
* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
* `M_USER_IN_USE` : The desired user ID is already taken.
* `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
* `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
claimed by an application service.
These errors may be returned at any stage of the registration process,
@ -200,7 +200,7 @@ paths:
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular ``kind`` of account is not
can be used to identify that a particular `kind` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
@ -251,12 +251,12 @@ paths:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server.
* `M_THREEPID_IN_USE` : The email address is already registered to an account on this server.
However, if the homeserver has the ability to send email, it is recommended that the server
instead send an email to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given email address
has an account on the homeserver in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
examples:
application/json: {
@ -301,12 +301,12 @@ paths:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
* `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server.
However, if the homeserver has the ability to send SMS message, it is recommended that the server
instead send an SMS message to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given phone number
has an account on the homeserver in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
examples:
application/json: {
@ -352,7 +352,7 @@ paths:
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
When `false`, the server can still take advantage of `the soft logout method <#soft-logout>`_
for the user's remaining devices.
example: true
auth:
@ -386,20 +386,20 @@ paths:
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
`/account/password` endpoint.
This API's parameters and response are identical to that of the
|/register/email/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given email address could be found. The server may instead send an
email to the given address prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
.. |/register/email/requestToken| replace:: `/register/email/requestToken`
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordEmail
@ -428,7 +428,7 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
@ -445,19 +445,19 @@ paths:
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
`/account/password` endpoint.
This API's parameters and response are identical to that of the
|/register/msisdn/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given phone number could be found. The server may instead send the SMS
to the given phone number prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the phone number itself, either by sending a
validation message itself or by using a service it has control over.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
.. |/register/msisdn/requestToken| replace:: `/register/msisdn/requestToken`
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordMSISDN
@ -486,7 +486,7 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
@ -511,7 +511,7 @@ paths:
The homeserver may change the flows available depending on whether a
valid access token is provided.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
Unlike other endpoints, this endpoint does not take an `id_access_token`
parameter because the homeserver is expected to sign the request to the
identity server instead.
security:
@ -533,11 +533,11 @@ paths:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the ``id_server``
If not provided, the homeserver MUST use the `id_server`
that was originally use to bind each identifier. If the
homeserver does not know which ``id_server`` that was,
it must return an ``id_server_unbind_result`` of
``no-support``.
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: "example.org"
responses:
200:
@ -552,12 +552,12 @@ paths:
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). ``success`` indicates
the user's 3PIDs from the identity server(s). `success` indicates
that all identifiers have been unbound from the identity server while
``no-support`` indicates that one or more identifiers failed to unbind
`no-support` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be ``success`` if the homeserver has no identifiers to unbind
must be `success` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
@ -612,15 +612,15 @@ paths:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be ``true`` when the server replies with 200 OK.
be `true` when the server replies with 200 OK.
400:
description: |-
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
* ``M_USER_IN_USE`` : The desired username is already taken.
* ``M_INVALID_USERNAME`` : The desired username is not a valid user name.
* ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace
* `M_USER_IN_USE` : The desired username is already taken.
* `M_INVALID_USERNAME` : The desired username is not a valid user name.
* `M_EXCLUSIVE` : The desired username is in the exclusive namespace
claimed by an application service.
examples:
application/json: {