# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector 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", "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: description: Identification information for the user. "$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 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", "well_known": { "m.homeserver": { "base_url": "https://example.org" }, "m.identity_server": { "base_url": "https://id.example.org" } } } 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. well_known: type: object 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. "$ref": "definitions/wellknown/full.yaml" 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. This can include one of the following error codes: * ``M_FORBIDDEN``: The provided authentication data was incorrect. * ``M_USER_DEACTIVATED``: The user has been deactivated. 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