diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0b2a8346..4933eb20 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1456,11 +1456,13 @@ forwarded to the login endpoint during the login process. For example: GET /_matrix/static/client/login/?device_id=GHTYAJCE -### Account registration and management +### Account registration {{% http-api spec="client-server" api="registration" %}} -#### Notes on password management +### Account 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" %}} diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml new file mode 100644 index 00000000..467af659 --- /dev/null +++ b/data/api/client-server/account_deactivation.yaml @@ -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 diff --git a/data/api/client-server/password_management.yaml b/data/api/client-server/password_management.yaml new file mode 100644 index 00000000..bf310ff9 --- /dev/null +++ b/data/api/client-server/password_management.yaml @@ -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 diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index a418d2d2..e7ede561 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -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.