matrix-spec/api/client-server/login.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 and Login API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/login":
    get:
      summary: Get the supported login types to authenticate users
      description: |-
        Gets the homeserver's supported login types to authenticate users. Clients
        should pick one of these and supply it as the ``type`` when logging in.
      operationId: getLoginFlows
      responses:
        200:
          description: The login types the homeserver supports
          examples:
            application/json: {
              "flows": [
                {"type": "m.login.password"}
              ]
            }
          schema:
            type: object
            properties:
              flows:
                type: array
                description: The homeserver's supported login types
                items:
                  type: object
                  title: LoginFlow
                  properties:
                    type:
                      description: |-
                        The login type. This is supplied as the ``type`` when
                        logging in.
                      type: string
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Session management
    post:
      summary: Authenticates the user.
      description: |-
        Authenticates the user, and issues an access token they can
        use to authorize themself 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`_.
      operationId: login
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: {
                "type": "m.login.password",
                "user": "cheeky_monkey",
                "password": "ilovebananas",
                "initial_device_display_name": "Jungle Phone"
              }
            properties:
              type:
                type: string
                enum: ["m.login.password", "m.login.token"]
                description: The login type being used.
              user:
                type: string
                description: The fully qualified user ID or just local part of the user ID, to log in.
              medium:
                type: string
                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.
              address:
                type: string
                description: Third party identifier for the user.
              password:
                type: string
                description: |-
                  Required when ``type`` is ``m.login.password``. The user's
                  password.
              token:
                type: string
                description: |-
                  Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login.
              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.
              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.
            required: ["type"]

      responses:
        200:
          description: The user has been authenticated.
          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 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 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 logged-in device. Will be the same as the
                  corresponding parameter in the request, if one was specified.
        400:
          description: |-
            Part of the request was invalid. For example, the login type may not be recognised.
          examples:
            application/json: {
                  "errcode": "M_UNKNOWN",
                  "error": "Bad login type."
              }
          schema:
            "$ref": "definitions/errors/error.yaml"
        403:
          description: |-
            The login attempt failed. For example, the password may have been incorrect.
          examples:
            application/json: {
              "errcode": "M_FORBIDDEN"}
          schema:
            "$ref": "definitions/errors/error.yaml"
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Session management