-
-
Notifications
You must be signed in to change notification settings - Fork 90
/
registration.yaml
665 lines (630 loc) · 27.8 KB
/
registration.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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
# Copyright 2016 OpenMarket 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.
swagger: '2.0'
info:
title: "Matrix Client-Server Registration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
paths:
"/register":
post:
summary: Register for an account on this homeserver.
description: |-
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api), except in
the cases where a guest account is being registered.
Register for an account on this homeserver.
There are two kinds of user account:
- `user` accounts. These accounts may use the full API described in this specification.
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
If registration is successful, this endpoint will issue an access token
the client can use to authorize itself in subsequent requests.
If the client does not supply a `device_id`, the server must
auto-generate one.
The server SHOULD register an account with a User ID based on the
`username` provided, if any. Note that the grammar of Matrix User ID
localparts is restricted, so the server MUST either map the provided
`username` onto a `user_id` in a logical manner, or reject any
`username` which does not comply to the grammar with
`M_INVALID_USERNAME`.
Matrix clients MUST NOT assume that localpart of the registered
`user_id` matches the provided `username`.
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).
When registering a guest account, all parameters in the request body
with the exception of `initial_device_display_name` MUST BE ignored
by the server. The server MUST pick a `device_id` for the account
regardless of input.
Any user ID returned by this API must conform to the grammar given in the
[Matrix specification](/appendices/#user-identifiers).
operationId: register
parameters:
- in: query
name: kind
type: string
# swagger-UI overrides the default with the example, so better make the
# example the default.
x-example: user
required: false
default: user
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the `register` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
type: string
description: |-
The basis for the localpart of the desired Matrix ID. If omitted,
the homeserver MUST generate a Matrix ID local part.
example: cheeky_monkey
password:
type: string
description: The desired password for the account.
example: ilovebananas
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.
example: GHTYAJCE
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.
example: Jungle Phone
inhibit_login:
type: boolean
description: |-
If true, an `access_token` and `device_id` should not be
returned from this call, therefore preventing an automatic
login. Defaults to false.
example: false
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
responses:
200:
description: The account has been registered.
examples:
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"device_id": "GHTYAJCE"
}
schema:
type: object
properties:
user_id:
type: string
description: |-
The fully-qualified Matrix user ID (MXID) that has been registered.
Any user ID returned by this API must conform to the grammar given in the
[Matrix specification](/appendices/#user-identifiers).
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
Required if the `inhibit_login` option is false.
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.
Omitted if the `inhibit_login` option is true.
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.
Omitted if the `inhibit_login` option is true.
x-addedInMatrixVersion: "1.3"
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 registered device. Will be the same as the
corresponding parameter in the request, if one was specified.
Required if the `inhibit_login` option is false.
required: ['user_id']
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* `M_USER_IN_USE` : The desired user ID is already taken.
* `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
* `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
claimed by an application service.
These errors may be returned at any stage of the registration process,
including after authentication if the requested user ID was registered
whilst the client was performing authentication.
Homeservers MUST perform the relevant checks and return these codes before
performing User-Interactive Authentication, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
examples:
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular `kind` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Account management
"/register/email/requestToken":
post:
summary: Begins the validation process for an email to be used during registration.
description: |-
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver
should validate the email itself, either by sending a validation email
itself or by using a service it has control over.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: |-
An email has been sent to the specified address. Note that this
may be an email containing the validation token or it may be
informing the user of an error.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* `M_THREEPID_IN_USE` : The email address is already registered to an account on this server.
However, if the homeserver has the ability to send email, it is recommended that the server
instead send an email to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given email address
has an account on the homeserver in question.
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Account management
"/register/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |-
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. The homeserver
should validate the phone number itself, either by sending a validation
message itself or by using a service it has control over.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: |-
An SMS message has been sent to the specified phone number. Note
that this may be an SMS message containing the validation token or
it may be informing the user of an error.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server.
However, if the homeserver has the ability to send SMS message, it is recommended that the server
instead send an SMS message to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given phone number
has an account on the homeserver in question.
* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
that is not trusted by this homeserver.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Account management
"/account/password":
post:
summary: "Changes a user's password."
description: |-
Changes the password for an account on this homeserver.
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
ensure the user changing the password is actually the owner of the
account.
An access token should be submitted to this endpoint if the client has
an active session.
The homeserver may change the flows available depending on whether a
valid access token is provided. The homeserver SHOULD NOT revoke the
access token provided in the request. Whether other access tokens for
the user are revoked depends on the request parameters.
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
new_password:
type: string
description: The new password for the account.
example: "ihatebananas"
logout_devices:
type: boolean
description: |-
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
required: ["new_password"]
responses:
200:
description: The password has been changed.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Account management
"/account/password/email/requestToken":
post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
description: |-
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
`/account/password` endpoint.
This API's parameters and response are identical to that of the
[`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
endpoint, except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given email address could be found. The server may instead send an
email to the given address prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
operationId: requestTokenToResetPasswordEmail
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The referenced third-party identifier is not recognised by the
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Email not found"
}
tags:
- Account management
"/account/password/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
description: |-
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
`/account/password` endpoint.
This API's parameters and response are identical to that of the
[`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
endpoint, except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given phone number could be found. The server may instead send the SMS
to the given phone number prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
The homeserver should validate the phone number itself, either by sending a
validation message itself or by using a service it has control over.
operationId: requestTokenToResetPasswordMSISDN
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
description: |-
The referenced third-party identifier is not recognised by the
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Phone number not found"
}
tags:
- Account management
"/account/deactivate":
post:
summary: "Deactivate a user's account."
description: |-
Deactivate the user's account, removing all ability for the user to
login again.
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
An access token should be submitted to this endpoint if the client has
an active session.
The homeserver may change the flows available depending on whether a
valid access token is provided.
Unlike other endpoints, this endpoint does not take an `id_access_token`
parameter because the homeserver is expected to sign the request to the
identity server instead.
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the `id_server`
that was originally use to bind each identifier. If the
homeserver does not know which `id_server` that was,
it must return an `id_server_unbind_result` of
`no-support`.
example: "example.org"
responses:
200:
description: The account has been deactivated.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "success"
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). `success` indicates
that all identifiers have been unbound from the identity server while
`no-support` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be `success` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Account management
"/register/available":
get:
summary: Checks to see if a username is available on the server.
description: |-
Checks to see if a username is available, and valid, for the server.
The server should check to ensure that, at the time of the request, the
username requested is available for use. This includes verifying that an
application service has not claimed the username and that the username
fits the server's desired requirements (for example, a server could dictate
that it does not permit usernames with underscores).
Matrix clients may wish to use this API prior to attempting registration,
however the clients must also be aware that using this API does not normally
reserve the username. This can mean that the username becomes unavailable
between checking its availability and attempting to register it.
operationId: checkUsernameAvailability
parameters:
- in: query
name: username
type: string
x-example: my_cool_localpart
required: true
default: my_cool_localpart
description: The username to check the availability of.
responses:
200:
description: The username is available
examples:
application/json: {
"available": true
}
schema:
type: object
properties:
available:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be `true` when the server replies with 200 OK.
400:
description: |-
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
* `M_USER_IN_USE` : The desired username is already taken.
* `M_INVALID_USERNAME` : The desired username is not a valid user name.
* `M_EXCLUSIVE` : The desired username is in the exclusive namespace
claimed by an application service.
examples:
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Account management