matrix-spec/api/client-server/registration.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 ID 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: |-
        Proxies the identity service API ``validate/email/requestToken``, but
        first checks that the given email address is not already associated
        with an account on this homeserver. See the Identity Service API for
        further information.
      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 service 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.
          schema:
            $ref: "../identity/definitions/sid.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 ID 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: |-
        Proxies the identity service API ``validate/msisdn/requestToken``, but
        first checks that the given phone number is not already associated
        with an account on this homeserver. See the Identity Service API for
        further information.
      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 service 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.
          schema:
            $ref: "../identity/definitions/sid.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 home server 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 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:
            "$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`_.

        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: 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: |-
        Proxies the identity service 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
      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 service 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:
            $ref: "../identity/definitions/sid.yaml"
  "/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: |-
        Proxies the identity service API ``validate/msisdn/requestToken``, but
        first checks that the given phone number **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/msisdn/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
        SMS message to the given address prompting the user to create an account.
        `M_THREEPID_IN_USE` may not be returned.

        .. |/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 service 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:
            $ref: "../identity/definitions/sid.yaml"
  "/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"
      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/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