mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
345 lines
14 KiB
YAML
345 lines
14 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 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`_.
|
|
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 ID Server.
|
|
example: false
|
|
username:
|
|
type: string
|
|
description: |-
|
|
The local part 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
|
|
responses:
|
|
200:
|
|
description: The account has been registered.
|
|
examples:
|
|
application/json: {
|
|
"user_id": "@cheeky_monkey:matrix.org",
|
|
"access_token": "abc123",
|
|
"home_server": "matrix.org",
|
|
"device_id": "GHTYAJCE"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
description: The fully-qualified Matrix ID that has been registered.
|
|
access_token:
|
|
type: string
|
|
description: |-
|
|
An access token for the account.
|
|
This access token can then be used to authorize other requests.
|
|
home_server:
|
|
type: string
|
|
description: The hostname of the homeserver on which the account has been registered.
|
|
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.
|
|
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."
|
|
}
|
|
401:
|
|
description: |-
|
|
The homeserver requires additional authentication information.
|
|
schema:
|
|
"$ref": "definitions/auth_response.yaml"
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
tags:
|
|
- User data
|
|
"/register/email/requestToken":
|
|
post:
|
|
summary: Requests a validation token be sent to the given email address for the purpose of registering an account
|
|
description: |-
|
|
Proxies the identity server API ``validate/email/requestToken``, but
|
|
first checks that the given email address is not already associated
|
|
with an account on this Home Server. Note that, for consistency,
|
|
this API takes JSON objects, though the Identity Server API takes
|
|
``x-www-form-urlencoded`` parameters. See the Identity Server API for
|
|
further information.
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
|
|
example: "id.matrix.org"
|
|
client_secret:
|
|
type: string
|
|
description: Client-generated secret string used to protect this session
|
|
example: "this_is_my_secret_string"
|
|
email:
|
|
type: string
|
|
description: The email address
|
|
example: "example@example.com"
|
|
send_attempt:
|
|
type: number
|
|
description: Used to distinguish protocol level retries from requests to re-send the email.
|
|
example: "1"
|
|
required: ["client_secret", "email", "send_attempt"]
|
|
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.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
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 home server 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 Home Server in question.
|
|
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
|
|
that is not trusted by this Home Server.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "The specified address is already in use"
|
|
}
|
|
schema:
|
|
type: object
|
|
"/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`_.
|
|
|
|
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: []
|
|
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/error.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: |-
|
|
Proxies the identity server API ``validate/email/requestToken``, but
|
|
first checks that the given email address **is** associated with an account
|
|
on this Home Server. 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.
|
|
|
|
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
|
|
|
|
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
|
responses:
|
|
200:
|
|
description: An email was sent to the given address
|
|
"/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: []
|
|
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"
|
|
responses:
|
|
200:
|
|
description: The account has been deactivated.
|
|
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/error.yaml"
|
|
tags:
|
|
- User data
|