mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-28 11:48:36 +01:00
62910a28cc
* master: Update example Fix 404s in links from room v1 spec Provide a more complete example of a "minimally-sized event" Revert signature change for redactable event test Clarify how many PDUs are in a given transaction object Clarify that the server shouldn't process retries for UIA Clarify when authorization and rate-limiting are not applicable Skip over partial event definitions in examples Rename example to invite_room_state Shorten references to StrippedState in s2s spec Fix examples of StrippedState in s2s spec Clarify exactly what StrippedState is Clarify that UIA stages cannot be attempted twice Fix test vectors with invalid JSON and signature Spec 3PID unbind API Spec MSISDN UIA support
737 lines
31 KiB
YAML
737 lines
31 KiB
YAML
# 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 Client-Server Registration API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
paths:
|
|
"/register":
|
|
post:
|
|
summary: Register for an account on this homeserver.
|
|
description: |-
|
|
This API endpoint uses the `User-Interactive Authentication API`_.
|
|
|
|
Register for an account on this homeserver.
|
|
|
|
There are two kinds of user account:
|
|
|
|
- `user` accounts. These accounts may use the full API described in this specification.
|
|
|
|
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
|
|
|
|
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
|
|
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
|
|
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``.
|
|
|
|
Matrix clients MUST NOT assume that localpart of the registered
|
|
``user_id`` matches the provided ``username``.
|
|
|
|
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`_.
|
|
operationId: register
|
|
parameters:
|
|
- in: query
|
|
name: kind
|
|
type: string
|
|
# swagger-UI overrides the default with the example, so better make the
|
|
# example the default.
|
|
x-example: user
|
|
required: false
|
|
default: user
|
|
enum:
|
|
- guest
|
|
- user
|
|
description: The kind of account to register. Defaults to `user`.
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the
|
|
user-interactive authentication API. Note that this
|
|
information is *not* used to define how the registered user
|
|
should be authenticated, but is instead used to
|
|
authenticate the ``register`` call itself. It should be
|
|
left empty, or omitted, unless an earlier call returned an
|
|
response with status code 401.
|
|
"$ref": "definitions/auth_data.yaml"
|
|
bind_email:
|
|
type: boolean
|
|
description: |-
|
|
If true, the server binds the email used for authentication to
|
|
the Matrix ID with the identity server.
|
|
example: false
|
|
bind_msisdn:
|
|
type: boolean
|
|
description: |-
|
|
If true, the server binds the phone number used for authentication
|
|
to the Matrix ID with the identity server.
|
|
example: false
|
|
username:
|
|
type: string
|
|
description: |-
|
|
The basis for the localpart of the desired Matrix ID. If omitted,
|
|
the homeserver MUST generate a Matrix ID local part.
|
|
example: cheeky_monkey
|
|
password:
|
|
type: string
|
|
description: The desired password for the account.
|
|
example: ilovebananas
|
|
device_id:
|
|
type: string
|
|
description: |-
|
|
ID of the client device. If this does not correspond to a
|
|
known client device, a new device will be created. The server
|
|
will auto-generate a device_id if this is not specified.
|
|
example: GHTYAJCE
|
|
initial_device_display_name:
|
|
type: string
|
|
description: |-
|
|
A display name to assign to the newly-created device. Ignored
|
|
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
|
|
returned from this call, therefore preventing an automatic
|
|
login. Defaults to false.
|
|
example: false
|
|
responses:
|
|
200:
|
|
description: The account has been registered.
|
|
examples:
|
|
application/json: {
|
|
"user_id": "@cheeky_monkey:matrix.org",
|
|
"access_token": "abc123",
|
|
"device_id": "GHTYAJCE"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
description: |-
|
|
The fully-qualified Matrix user ID (MXID) that has been registered.
|
|
|
|
Any user ID returned by this API must conform to the grammar given in the
|
|
`Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.
|
|
access_token:
|
|
type: string
|
|
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.
|
|
home_server:
|
|
type: string
|
|
description: |-
|
|
The server_name of the homeserver on which the account has
|
|
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.
|
|
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: ['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
|
|
claimed by an application service.
|
|
|
|
These errors may be returned at any stage of the registration process,
|
|
including after authentication if the requested user ID was registered
|
|
whilst the client was performing authentication.
|
|
|
|
Homeservers MUST perform the relevant checks and return these codes before
|
|
performing User-Interactive Authentication, although they may also return
|
|
them after authentication is completed if, for example, the requested user ID
|
|
was registered whilst the client was performing authentication.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_USER_IN_USE",
|
|
"error": "Desired user ID is already taken."
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
401:
|
|
description: |-
|
|
The homeserver requires additional authentication information.
|
|
schema:
|
|
"$ref": "definitions/auth_response.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|
|
"/register/email/requestToken":
|
|
post:
|
|
summary: Begins the validation process for an email to be used during registration.
|
|
description: |-
|
|
The homeserver should check that the given email address is **not**
|
|
already associated with an account on this homeserver. The homeserver
|
|
has the choice of validating the email address itself, or proxying the
|
|
request to the ``validate/email/requestToken`` Identity Server API on
|
|
the server sent in ``id_server``.
|
|
operationId: requestTokenToRegisterEmail
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/request_email_validation.yaml"
|
|
- type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The hostname of the identity server to communicate with. May
|
|
optionally include a port.
|
|
example: "id.example.com"
|
|
required: ['id_server']
|
|
responses:
|
|
200:
|
|
description: |-
|
|
An email has been sent to the specified address.
|
|
Note that this may be an email containing the validation token or it may be informing
|
|
the user of an error.
|
|
|
|
``submit_url`` is an optional field containing a URL where the
|
|
client must submit a validation token to, with identical parameters
|
|
to the Identity Service API's ``/validate/email/submitToken``
|
|
endpoint. The homeserver will send this token to the user, which
|
|
should then be prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's involvement.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client
|
|
must submit a validation token to, with identical
|
|
parameters to the Identity Service API's
|
|
``/validate/email/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which should then be
|
|
prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's
|
|
involvement.
|
|
example: "https://example.org/path/to/submitToken"
|
|
403:
|
|
description: The homeserver does not permit the address to be bound.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
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.
|
|
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
|
|
that is not trusted by this homeserver.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "The specified address is already in use"
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
"/register/msisdn/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
|
|
description: |-
|
|
The homeserver should check that the given phone number is **not**
|
|
already associated with an account on this homeserver. The homeserver
|
|
has the choice of validating the phone number itself, or proxying the
|
|
request to the ``validate/msisdn/requestToken`` Identity Server API on
|
|
the server sent in ``id_server``.
|
|
operationId: requestTokenToRegisterMSISDN
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
|
|
- type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The hostname of the identity server to communicate with. May
|
|
optionally include a port.
|
|
example: "id.example.com"
|
|
required: ['id_server']
|
|
responses:
|
|
200:
|
|
description: |-
|
|
An SMS message has been sent to the specified phone number.
|
|
Note that this may be an SMS message containing the validation token or it may be informing
|
|
the user of an error.
|
|
|
|
``submit_url`` is an optional field containing a URL where the
|
|
client must submit a validation token to, with identical parameters
|
|
to the Identity Service API's ``/validate/msisdn/submitToken``
|
|
endpoint. The homeserver will send this token to the user, which
|
|
should then be prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's involvement.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client
|
|
must submit a validation token to, with identical
|
|
parameters to the Identity Service API's
|
|
``/validate/email/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which should then be
|
|
prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's
|
|
involvement.
|
|
example: "https://example.org/path/to/submitToken"
|
|
403:
|
|
description: The homeserver does not permit the address to be bound.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
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.
|
|
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
|
|
that is not trusted by this homeserver.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "The specified address is already in use"
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
"/account/password":
|
|
post:
|
|
summary: "Changes a user's password."
|
|
description: |-
|
|
Changes the password for an account on this homeserver.
|
|
|
|
This API endpoint uses the `User-Interactive Authentication API`_ to
|
|
ensure the user changing the password is actually the owner of the
|
|
account.
|
|
|
|
An access token should be submitted to this endpoint if the client has
|
|
an active session.
|
|
|
|
The homeserver may change the flows available depending on whether a
|
|
valid access token is provided. The homeserver SHOULD NOT revoke the
|
|
access token provided in the request, however all other access tokens
|
|
for the user should be revoked if the request succeeds.
|
|
security:
|
|
- accessToken: []
|
|
operationId: changePassword
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
new_password:
|
|
type: string
|
|
description: The new password for the account.
|
|
example: "ihatebananas"
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the user-interactive authentication API.
|
|
"$ref": "definitions/auth_data.yaml"
|
|
required: ["new_password"]
|
|
responses:
|
|
200:
|
|
description: The password has been changed.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
401:
|
|
description: |-
|
|
The homeserver requires additional authentication information.
|
|
schema:
|
|
"$ref": "definitions/auth_response.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|
|
"/account/password/email/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
|
|
description: |-
|
|
The homeserver should check that the given email address **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
``account/password`` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the HS API
|
|
|/register/email/requestToken|_ except that ``M_THREEPID_NOT_FOUND``
|
|
may be returned if no account matching the given email address could be
|
|
found. The server may instead send an email to the given address
|
|
prompting the user to create an account. ``M_THREEPID_IN_USE`` may not
|
|
be returned.
|
|
|
|
The homeserver has the choice of validating the email address itself,
|
|
or proxying the request to the ``validate/email/requestToken`` Identity
|
|
server api on the server sent in ``id_server``.
|
|
|
|
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
|
|
|
|
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
|
operationId: requestTokenToResetPasswordEmail
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/request_email_validation.yaml"
|
|
- type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The hostname of the identity server to communicate with. May
|
|
optionally include a port.
|
|
example: "id.example.com"
|
|
required: ['id_server']
|
|
responses:
|
|
200:
|
|
description: An email was sent to the given address.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client must
|
|
submit a validation token to, with identical parameters
|
|
to the Identity Service API's
|
|
``/validate/email/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which should then be
|
|
prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's
|
|
involvement.
|
|
example: "https://example.org/path/to/submitToken"
|
|
403:
|
|
description: |-
|
|
The homeserver does not allow the third party identifier as a
|
|
contact option.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
description: |-
|
|
The referenced third party identifier is not recognised by the
|
|
homeserver, or the request was invalid
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_NOT_FOUND",
|
|
"error": "Email not found"
|
|
}
|
|
"/account/password/msisdn/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
|
|
description: |-
|
|
The homeserver should check that the given phone number **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
``account/password`` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the HS API
|
|
|/register/msisdn/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` may
|
|
be returned if no account matching the given phone number could be
|
|
found. The server may instead send the SMS to the given phone number
|
|
prompting the user to create an account. ``M_THREEPID_IN_USE`` may not
|
|
be returned.
|
|
|
|
The homeserver has the choice of validating the phone number itself, or
|
|
proxying the request to the ``validate/msisdn/requestToken`` Identity
|
|
server api on the server sent in ``id_server``.
|
|
|
|
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
|
|
|
|
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
|
operationId: requestTokenToResetPasswordMSISDN
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
|
|
- type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The hostname of the identity server to communicate with. May
|
|
optionally include a port.
|
|
example: "id.example.com"
|
|
required: ['id_server']
|
|
responses:
|
|
200:
|
|
description: An SMS message was sent to the given phone number.
|
|
schema:
|
|
allOf:
|
|
- $ref: "../identity/definitions/sid.yaml"
|
|
- type: object
|
|
properties:
|
|
submit_url:
|
|
type: string
|
|
description: |-
|
|
An optional field containing a URL where the client must
|
|
submit a validation token to, with identical parameters
|
|
to the Identity Service API's
|
|
``/validate/msisdn/submitToken`` endpoint. The homeserver
|
|
will send this token to the user, which should then be
|
|
prompted to provide it to the client.
|
|
|
|
If this field is not present, the client can assume that
|
|
verification will happen without the client's
|
|
involvement.
|
|
example: "https://example.org/path/to/submitToken"
|
|
403:
|
|
description: |-
|
|
The homeserver does not allow the third party identifier as a
|
|
contact option.
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_DENIED",
|
|
"error": "Third party identifier is not allowed"
|
|
}
|
|
400:
|
|
description: |-
|
|
The referenced third party identifier is not recognised by the
|
|
homeserver, or the request was invalid
|
|
schema:
|
|
$ref: "definitions/errors/error.yaml"
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_NOT_FOUND",
|
|
"error": "Phone number not found"
|
|
}
|
|
"/account/deactivate":
|
|
post:
|
|
summary: "Deactivate a user's account."
|
|
description: |-
|
|
Deactivate the user's account, removing all ability for the user to
|
|
login again.
|
|
|
|
This API endpoint uses the `User-Interactive Authentication API`_.
|
|
|
|
An access token should be submitted to this endpoint if the client has
|
|
an active session.
|
|
|
|
The homeserver may change the flows available depending on whether a
|
|
valid access token is provided.
|
|
security:
|
|
- accessToken: []
|
|
operationId: deactivateAccount
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the user-interactive authentication API.
|
|
"$ref": "definitions/auth_data.yaml"
|
|
id_server:
|
|
type: string
|
|
description: |-
|
|
The identity server to unbind all of the user's 3PIDs from.
|
|
If not provided, the homeserver MUST use the ``id_server``
|
|
that was originally use to bind each identifier. If the
|
|
homeserver does not know which ``id_server`` that was,
|
|
it must return an ``id_server_unbind_result`` of
|
|
``no-support``.
|
|
example: "example.org"
|
|
responses:
|
|
200:
|
|
description: The account has been deactivated.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server_unbind_result:
|
|
type: string
|
|
enum:
|
|
- "success"
|
|
- "no-support"
|
|
description: |-
|
|
An indicator as to whether or not the homeserver was able to unbind
|
|
the user's 3PIDs from the identity server(s). ``success`` indicates
|
|
that all identifiers have been unbound from the identity server while
|
|
``no-support`` indicates that one or more identifiers failed to unbind
|
|
due to the identity server refusing the request or the homeserver
|
|
being unable to determine an identity server to unbind from. This
|
|
must be ``success`` if the homeserver has no identifiers to unbind
|
|
for the user.
|
|
example: "success"
|
|
required:
|
|
- id_server_unbind_result
|
|
401:
|
|
description: |-
|
|
The homeserver requires additional authentication information.
|
|
schema:
|
|
"$ref": "definitions/auth_response.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|
|
"/register/available":
|
|
get:
|
|
summary: Checks to see if a username is available on the server.
|
|
description: |-
|
|
Checks to see if a username is available, and valid, for the server.
|
|
|
|
The server should check to ensure that, at the time of the request, the
|
|
username requested is available for use. This includes verifying that an
|
|
application service has not claimed the username and that the username
|
|
fits the server's desired requirements (for example, a server could dictate
|
|
that it does not permit usernames with underscores).
|
|
|
|
Matrix clients may wish to use this API prior to attempting registration,
|
|
however the clients must also be aware that using this API does not normally
|
|
reserve the username. This can mean that the username becomes unavailable
|
|
between checking its availability and attempting to register it.
|
|
operationId: checkUsernameAvailability
|
|
parameters:
|
|
- in: query
|
|
name: username
|
|
type: string
|
|
x-example: my_cool_localpart
|
|
required: true
|
|
default: my_cool_localpart
|
|
description: The username to check the availability of.
|
|
responses:
|
|
200:
|
|
description: The username is available
|
|
examples:
|
|
application/json: {
|
|
"available": true
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
available:
|
|
type: boolean
|
|
description: |-
|
|
A flag to indicate that the username is available. This should always
|
|
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
|
|
claimed by an application service.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_USER_IN_USE",
|
|
"error": "Desired user ID is already taken."
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/errors/rate_limited.yaml"
|
|
tags:
|
|
- User data
|