mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-08 04:24:10 +01:00
27b4cdcc9e
I did a quick search of the "deprecated" word in the data folder and set the field where the description says that a property is deprecated. This does not change the rendering of the spec because the descriptions already talk about the deprecation, but it can be used by tools that rely on the OpenAPI definitions and JSON Schemas. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
297 lines
12 KiB
YAML
297 lines
12 KiB
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
|
|
description: |-
|
|
The login type being used.
|
|
|
|
This must be a type returned in one of the flows of the
|
|
response of the [`GET /login`](/client-server-api/#get_matrixclientv3login)
|
|
endpoint, like `m.login.password` or `m.login.token`.
|
|
identifier:
|
|
$ref: definitions/user_identifier.yaml
|
|
user:
|
|
type: string
|
|
deprecated: true
|
|
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
|
|
deprecated: true
|
|
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
|
|
deprecated: true
|
|
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
|
|
deprecated: true
|
|
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:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|