matrix-spec-proposals/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":
    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`_.        
      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``. The login token.
              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",
                "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 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."
              }              
        403:
          description: |-
                        The login attempt failed. For example, the password may have been incorrect.
          examples:
            application/json: |-
                            {"errcode": "M_FORBIDDEN"}
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/error.yaml"
      tags:
        - Session management