You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
638 lines
26 KiB
YAML
638 lines
26 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`_, except in
|
|
the cases where a guest account is being registered.
|
|
|
|
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`_.
|
|
|
|
When registering a guest account, all parameters in the request body
|
|
with the exception of ``initial_device_display_name`` MUST BE ignored
|
|
by the server. The server MUST pick a ``device_id`` for the account
|
|
regardless of input.
|
|
|
|
Any user ID returned by this API must conform to the grammar given in the
|
|
`Matrix specification <../appendices.html#user-identifiers>`_.
|
|
operationId: register
|
|
parameters:
|
|
- in: query
|
|
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
|
|
required: true
|
|
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.
|
|
allOf:
|
|
- "$ref": "definitions/auth_data.yaml"
|
|
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 <../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"
|
|
403:
|
|
description: |-
|
|
The homeserver does not permit registering the account. This response
|
|
can be used to identify that a particular ``kind`` of account is not
|
|
allowed, or that registration is generally not supported by the homeserver.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Registration is disabled"
|
|
}
|
|
schema:
|
|
"$ref": "definitions/errors/error.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$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 must check that the given email address is **not**
|
|
already associated with an account on this homeserver. The homeserver
|
|
should validate the email itself, either by sending a validation email
|
|
itself or by using a service it has control over.
|
|
operationId: requestTokenToRegisterEmail
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "definitions/request_email_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: |-
|
|
An email has been sent to the specified address. Note that this
|
|
may be an email containing the validation token or it may be
|
|
informing the user of an error.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
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 must check that the given phone number is **not**
|
|
already associated with an account on this homeserver. The homeserver
|
|
should validate the phone number itself, either by sending a validation
|
|
message itself or by using a service it has control over.
|
|
operationId: requestTokenToRegisterMSISDN
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "definitions/request_msisdn_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: |-
|
|
An SMS message has been sent to the specified phone number. Note
|
|
that this may be an SMS message containing the validation token or
|
|
it may be informing the user of an error.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
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. Whether other access tokens for
|
|
the user are revoked depends on the request parameters.
|
|
security:
|
|
- accessToken: []
|
|
operationId: changePassword
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
new_password:
|
|
type: string
|
|
description: The new password for the account.
|
|
example: "ihatebananas"
|
|
logout_devices:
|
|
type: boolean
|
|
description: |-
|
|
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>`_
|
|
for the user's remaining devices.
|
|
example: true
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the user-interactive authentication API.
|
|
allOf:
|
|
- "$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 must check that the given email address **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
``/account/password`` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the
|
|
|/register/email/requestToken|_ endpoint, except that
|
|
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
|
|
given email address could be found. The server may instead send an
|
|
email to the given address prompting the user to create an account.
|
|
``M_THREEPID_IN_USE`` may not be returned.
|
|
|
|
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: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
|
operationId: requestTokenToResetPasswordEmail
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "definitions/request_email_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: An email was sent to the given address.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
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. 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:
|
|
$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 must check that the given phone number **is
|
|
associated** with an account on this homeserver. This API should be
|
|
used to request validation tokens when authenticating for the
|
|
``/account/password`` endpoint.
|
|
|
|
This API's parameters and response are identical to that of the
|
|
|/register/msisdn/requestToken|_ endpoint, except that
|
|
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
|
|
given phone number could be found. The server may instead send the SMS
|
|
to the given phone number prompting the user to create an account.
|
|
``M_THREEPID_IN_USE`` may not be returned.
|
|
|
|
The homeserver 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: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
|
operationId: requestTokenToResetPasswordMSISDN
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "definitions/request_msisdn_validation.yaml"
|
|
responses:
|
|
200:
|
|
description: An SMS message was sent to the given phone number.
|
|
schema:
|
|
$ref: "definitions/request_token_response.yaml"
|
|
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. 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:
|
|
$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.
|
|
|
|
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:
|
|
- accessToken: []
|
|
operationId: deactivateAccount
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
auth:
|
|
description: |-
|
|
Additional authentication information for the user-interactive authentication API.
|
|
allOf:
|
|
- $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
|