matrix-spec/data/api/client-server/login.yaml

# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
# Copyright 2022 The Matrix.org Foundation C.I.C.
#
# 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server Registration and Login API
  version: 1.0.0
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
          content:
            application/json:
              schema:
                type: object
                properties:
                  flows:
                    type: array
                    description: The homeserver's supported login types
                    items:
                      type: object
                      title: LoginFlow
                      required:
                        - type
                      properties:
                        type:
                          description: |-
                            The login type. This is supplied as the `type` when
                            logging in.
                          type: string
                        get_login_token:
                          type: boolean
                          x-addedInMatrixVersion: "1.7"
                          description: |-
                            If `type` is `m.login.token`, an optional field to indicate
                            to the unauthenticated client that the homeserver supports
                            the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
                            endpoint. Note that supporting the endpoint does not
                            necessarily indicate that the user attempting to log in will
                            be able to generate such a token.
              examples:
                response:
                  value: {
                    "flows": [
                      {
                        "type": "m.login.password"
                      },
                      {
                        "type": "m.login.token",
                        "get_login_token": true
                      }
                    ]
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              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](/client-server-api/#relationship-between-access-tokens-and-devices).
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "type": "m.login.password",
                "identifier": {
                  "type": "m.id.user",
                  "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.
                identifier:
                  $ref: definitions/user_identifier.yaml
                user:
                  type: string
                  description: The fully qualified user ID or just local part of the user ID, to
                    log in.  Deprecated in favour of `identifier`.
                medium:
                  type: string
                  description: When logging in using a third-party identifier, the medium of the
                    identifier. Must be 'email'.  Deprecated in favour of
                    `identifier`.
                address:
                  type: string
                  description: Third-party identifier for the user.  Deprecated in favour of
                    `identifier`.
                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 given
                    device ID must not be the same as a
                    [cross-signing](/client-server-api/#cross-signing) key ID.
                    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.
                refresh_token:
                  type: boolean
                  description: If true, the client supports refresh tokens.
                  x-addedInMatrixVersion: "1.3"
              required:
                - type
        required: true
      responses:
        "200":
          description: The user has been authenticated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    description: The fully-qualified Matrix ID for the account.
                  access_token:
                    type: string
                    description: |-
                      An access token for the account.
                      This access token can then be used to authorize other requests.
                  refresh_token:
                    type: string
                    description: |-
                      A refresh token for the account. This token can be used to
                      obtain a new access token when it expires by calling the
                      `/refresh` endpoint.
                    x-addedInMatrixVersion: "1.3"
                  expires_in_ms:
                    type: integer
                    description: |-
                      The lifetime of the access token, in milliseconds. Once
                      the access token has expired a new access token can be
                      obtained by using the provided refresh token. If no
                      refresh token is provided, the client will need to re-log in
                      to obtain a new access token. If not given, the client can
                      assume that the access token will not expire.
                    x-addedInMatrixVersion: "1.3"
                  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.
                  well_known:
                    description: |-
                      Optional client configuration provided by the server. If present,
                      clients SHOULD use the provided object to reconfigure themselves,
                      optionally validating the URLs within. This object takes the same
                      form as the one returned from .well-known autodiscovery.
                    allOf:
                      - $ref: definitions/wellknown/full.yaml
                required:
                  - access_token
                  - device_id
                  - user_id
              examples:
                response:
                  value: {
                    "user_id": "@cheeky_monkey:matrix.org",
                    "access_token": "abc123",
                    "refresh_token": "def456",
                    "expires_in_ms": 60000,
                    "device_id": "GHTYAJCE",
                    "well_known": {
                      "m.homeserver": {
                        "base_url": "https://example.org"
                      },
                      "m.identity_server": {
                        "base_url": "https://id.example.org"
                      }
                    }
                  }
        "400":
          description: Part of the request was invalid. For example, the login type may
            not be recognised.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_UNKNOWN",
                    "error": "Bad login type."
                  }
        "403":
          description: |-
            The login attempt failed. This can include one of the following error codes:
              * `M_FORBIDDEN`: The provided authentication data was incorrect
                or the requested device ID is the same as a cross-signing key
                ID.
              * `M_USER_DEACTIVATED`: The user has been deactivated.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Session management
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    $ref: definitions/security.yaml