# 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