-
Notifications
You must be signed in to change notification settings - Fork 379
/
login.yaml
208 lines (204 loc) · 7.88 KB
/
login.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
# 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. For example, the password may have been incorrect.
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