You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/api/client-server/login.yaml

143 lines
5.2 KiB
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