Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-19 20:43:42 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge cf45f4d17b into 4ed55a60ec

Browse source
This commit is contained in:
Kévin Commaille 2025-05-20 20:37:04 +02:00 committed by GitHub
parent 4ed55a60ec cf45f4d17b
commit ddaf20fb1d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 397 additions and 312 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2141.clarification Normal file
View file

@ -0,0 +1 @@
Split account registration and management section and OpenAPI definitions.

16
content/client-server-api/_index.md
View file

@ -439,7 +439,7 @@ endpoints it supports.
Most API endpoints require the user to identify themselves by presenting
previously obtained credentials in the form of an access token.
An access token is typically obtained via the [Login](#login) or
[Registration](#account-registration-and-management) processes. Access tokens
[Registration](#account-registration) processes. Access tokens
can expire; a new access token can be generated by using a refresh token.
{{% boxes/note %}}
@ -494,7 +494,7 @@ used to generate a new access token and refresh token, the new access
and refresh tokens are now bound to the device associated with the
initial refresh token.
By default, the [Login](#login) and [Registration](#account-registration-and-management)
By default, the [Login](#login) and [Registration](#account-registration)
processes auto-generate a new `device_id`. A client is also free to
generate its own `device_id` or, provided the user remains the same,
reuse a device: in either case the client should pass the `device_id` in
@ -1458,9 +1458,11 @@ forwarded to the login endpoint during the login process. For example:
### Account registration and management
#### Account Registration
{{% http-api spec="client-server" api="registration" %}}
#### Notes on password management
#### Password management
{{% boxes/warning %}}
Clients SHOULD enforce that the password provided is suitably complex.
@ -1469,6 +1471,14 @@ number and a symbol and be at a minimum 8 characters in length. Servers
MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
{{% /boxes/warning %}}
{{% http-api spec="client-server" api="password_management" %}}
#### Account deactivation
{{% http-api spec="client-server" api="account_deactivation" %}}
### Account moderation
#### Account locking
{{% added-in v="1.12" %}}

141
data/api/client-server/account_deactivation.yaml Normal file
View file

@ -0,0 +1,141 @@
# 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.
openapi: 3.1.0
info:
title: Matrix Client-Server Account Deactivation API
version: 1.0.0
paths:
/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:
- {}
- accessTokenQuery: []
- accessTokenBearer: []
operationId: deactivateAccount
requestBody:
content:
application/json:
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
erase:
x-addedInMatrixVersion: "1.10"
type: boolean
description: |-
Whether the user would like their content to be erased as
much as possible from the server.
Erasure means that any users (or servers) which join the
room after the erasure request are served redacted copies of
the events sent by this account. Users which had visibility
on those events prior to the erasure are still able to see
unredacted copies. No redactions are sent and the erasure
request is not shared over federation, so other servers
might still serve unredacted copies.
The server should additionally erase any non-event data
associated with the user, such as [account data](/client-server-api/#client-config)
and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
Defaults to `false` if not present.
required: true
responses:
"200":
description: The account has been deactivated.
content:
application/json:
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.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Account 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

242
data/api/client-server/password_management.yaml Normal file
View file

@ -0,0 +1,242 @@
# 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.
openapi: 3.1.0
info:
title: Matrix Client-Server Password Management API
version: 1.0.0
paths:
/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:
- {}
- accessTokenQuery: []
- accessTokenBearer: []
operationId: changePassword
requestBody:
content:
application/json:
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
required: true
responses:
"200":
description: The password has been changed.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
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
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
required: true
responses:
"200":
description: An email was sent to the given address.
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Email not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
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
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
"200":
description: An SMS message was sent to the given phone number.
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Phone number not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account 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

309
data/api/client-server/registration.yaml
View file

@ -373,315 +373,6 @@ paths:
}
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:
- {}
- accessTokenQuery: []
- accessTokenBearer: []
operationId: changePassword
requestBody:
content:
application/json:
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
required: true
responses:
"200":
description: The password has been changed.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
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
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
required: true
responses:
"200":
description: An email was sent to the given address.
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Email not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
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
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
"200":
description: An SMS message was sent to the given phone number.
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"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.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_NOT_FOUND",
"error": "Phone number not found"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
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:
- {}
- accessTokenQuery: []
- accessTokenBearer: []
operationId: deactivateAccount
requestBody:
content:
application/json:
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
erase:
x-addedInMatrixVersion: "1.10"
type: boolean
description: |-
Whether the user would like their content to be erased as
much as possible from the server.
Erasure means that any users (or servers) which join the
room after the erasure request are served redacted copies of
the events sent by this account. Users which had visibility
on those events prior to the erasure are still able to see
unredacted copies. No redactions are sent and the erasure
request is not shared over federation, so other servers
might still serve unredacted copies.
The server should additionally erase any non-event data
associated with the user, such as [account data](/client-server-api/#client-config)
and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
Defaults to `false` if not present.
required: true
responses:
"200":
description: The account has been deactivated.
content:
application/json:
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.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
content:
application/json:
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.