async-matrix 0.1.3 → 1.1.0

data/data/matrix-spec/api/client-server/account-data.yaml

@@ -0,0 +1,389 @@
+# Copyright 2016 OpenMarket 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Client Config API
+  version: 1.0.0
+paths:
+  "/user/{userId}/account_data/{type}":
+    put:
+      summary: Set some account data for the user.
+      description: |-
+        Set some account data for the client. This config is only visible to the user
+        that set the account data. The config will be available to clients through the
+        top-level `account_data` field in the homeserver response to
+        [/sync](/client-server-api/#get_matrixclientv3sync).
+      operationId: setAccountData
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The ID of the user to set account data for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: type
+          required: true
+          description: |-
+            The event type of the account data to set. Custom types should be
+            namespaced to avoid clashes.
+          example: org.example.custom.config
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "custom_account_data_key": "custom_config_value"
+              }
+        description: The content of the account data.
+        required: true
+      responses:
+        "200":
+          description: The account data was successfully added.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |-
+            The request body is not a JSON object. Errcode: `M_BAD_JSON`
+            or `M_NOT_JSON`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_JSON",
+                    "error": "Content must be a JSON object."
+                  }
+        "403":
+          description: |-
+            The access token provided is not authorized to modify this user's account 
+            data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "405":
+          description: |-
+            This `type` of account data is controlled by the server; it cannot be
+            modified by clients. Errcode: `M_BAD_JSON`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_BAD_JSON",
+                    "error": "Cannot set m.fully_read through this API."
+                  }
+      tags:
+        - User data
+    get:
+      summary: Get some account data for the user.
+      description: |-
+        Get some account data for the client. This config is only visible to the user
+        that set the account data.
+      operationId: getAccountData
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The ID of the user to get account data for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: type
+          required: true
+          description: |-
+            The event type of the account data to get. Custom types should be
+            namespaced to avoid clashes.
+          example: org.example.custom.config
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The account data content for the given type.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "custom_account_data_key": "custom_config_value"
+                }
+        "403":
+          description: |-
+            The access token provided is not authorized to retrieve this user's account 
+            data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "404":
+          description: |-
+            No account data has been provided for this user with the given `type`.
+            Errcode: `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Account data not found."
+                  }
+      tags:
+        - User data
+  "/user/{userId}/rooms/{roomId}/account_data/{type}":
+    put:
+      summary: Set some account data for the user that is specific to a room.
+      description: |-
+        Set some account data for the client on a given room. This config is only
+        visible to the user that set the account data. The config will be delivered to
+        clients in the per-room entries via [/sync](/client-server-api/#get_matrixclientv3sync).
+      operationId: setAccountDataPerRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The ID of the user to set account data for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to set account data on.
+          example: "!726s6s6q:example.com"
+          schema:
+            type: string
+        - in: path
+          name: type
+          required: true
+          description: |-
+            The event type of the account data to set. Custom types should be
+            namespaced to avoid clashes.
+          example: org.example.custom.room.config
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "custom_account_data_key": "custom_account_data_value"
+              }
+        description: The content of the account data.
+        required: true
+      responses:
+        "200":
+          description: The account data was successfully added.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |-
+            The request body is not a JSON object (errcode `M_BAD_JSON` or
+            `M_NOT_JSON`), or the given `roomID` is not a valid room ID
+            (errcode `M_INVALID_PARAM`).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_JSON",
+                    "error": "Content must be a JSON object."
+                  }
+        "403":
+          description: |-
+            The access token provided is not authorized to modify this user's account 
+            data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "405":
+          description: |-
+            This `type` of account data is controlled by the server; it cannot be
+            modified by clients. Errcode: `M_BAD_JSON`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_BAD_JSON",
+                    "error": "Cannot set m.fully_read through this API."
+                  }
+      tags:
+        - User data
+    get:
+      summary: Get some account data for the user that is specific to a room.
+      description: |-
+        Get some account data for the client on a given room. This config is only
+        visible to the user that set the account data.
+      operationId: getAccountDataPerRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The ID of the user to get account data for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to get account data for.
+          example: "!726s6s6q:example.com"
+          schema:
+            type: string
+        - in: path
+          name: type
+          required: true
+          description: |-
+            The event type of the account data to get. Custom types should be
+            namespaced to avoid clashes.
+          example: org.example.custom.room.config
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The account data content for the given type.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "custom_account_data_key": "custom_config_value"
+                }
+        "400":
+          description: "The given `roomID` is not a valid room ID. Errcode:
+            `M_INVALID_PARAM`."
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "@notaroomid:example.org is not a valid room ID."
+                  }
+        "403":
+          description: |-
+            The access token provided is not authorized to retrieve this user's account 
+            data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot add account data for other users."
+                  }
+        "404":
+          description: |-
+            No account data has been provided for this user and this room with the 
+            given `type`. Errcode: `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room account data not found."
+                  }
+      tags:
+        - User data
+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

data/data/matrix-spec/api/client-server/account_deactivation.yaml

@@ -0,0 +1,149 @@
+# 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.
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, and MAY use the `action=org.matrix.account_deactivate`
+        parameter.
+        {{% /boxes/warning %}}
+      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