mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-01-01 13:38:37 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
140 lines
5.1 KiB
YAML
140 lines
5.1 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
|