async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,620 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2019 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 Administrative Contact API
+  version: 1.0.0
+paths:
+  /account/3pid:
+    get:
+      summary: Gets a list of a user's third-party identifiers.
+      description: |-
+        Gets a list of the third-party identifiers that the homeserver has
+        associated with the user's account.
+
+        This is *not* the same as the list of third-party identifiers bound to
+        the user's Matrix ID in identity servers.
+
+        Identifiers in this list may be used by the homeserver as, for example,
+        identifiers that it will accept to reset the user's account password.
+      operationId: getAccount3PIDs
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  threepids:
+                    type: array
+                    items:
+                      type: object
+                      title: Third-party identifier
+                      properties:
+                        medium:
+                          type: string
+                          description: The medium of the third-party identifier.
+                          enum:
+                            - email
+                            - msisdn
+                        address:
+                          type: string
+                          description: The third-party identifier address.
+                        validated_at:
+                          type: integer
+                          format: int64
+                          description: |-
+                            The timestamp, in milliseconds, when the identifier was
+                            validated by the identity server.
+                        added_at:
+                          type: integer
+                          format: int64
+                          description: The timestamp, in milliseconds, when the homeserver associated the
+                            third-party identifier with the user.
+                      required:
+                        - medium
+                        - address
+                        - validated_at
+                        - added_at
+              examples:
+                response:
+                  value: {
+                    "threepids": [
+                      {
+                        "medium": "email",
+                        "address": "monkey@banana.island",
+                        "validated_at": 1535176800000,
+                        "added_at": 1535336848756
+                      }
+                    ]
+                  }
+      tags:
+        - Account management
+    post:
+      summary: Adds contact information to the user's account.
+      description: |-
+        Adds contact information to the user's account.
+
+        This endpoint is deprecated in favour of the more specific `/3pid/add`
+        and `/3pid/bind` endpoints.
+
+        **Note:**
+        Previously this endpoint supported a `bind` parameter. This parameter
+        has been removed, making this endpoint behave as though it was `false`.
+        This results in this endpoint being an equivalent to `/3pid/bind` rather
+        than dual-purpose.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+      operationId: post3PIDs
+      deprecated: true
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                three_pid_creds:
+                  title: ThreePidCredentials
+                  type: object
+                  description: The third-party credentials to associate with the account.
+                  properties:
+                    client_secret:
+                      type: string
+                      description: The client secret used in the session with the identity server.
+                    id_server:
+                      type: string
+                      description: The identity server to use.
+                    id_access_token:
+                      type: string
+                      description: |-
+                        An access token previously registered with the identity server. Servers
+                        can treat this as optional to distinguish between r0.5-compatible clients
+                        and this specification version.
+                    sid:
+                      type: string
+                      description: The session identifier given by the identity server.
+                  required:
+                    - client_secret
+                    - id_server
+                    - id_access_token
+                    - sid
+              required:
+                - three_pid_creds
+              example: {
+                "three_pid_creds": {
+                  "id_server": "matrix.org",
+                  "id_access_token": "abc123_OpaqueString",
+                  "sid": "abc123987",
+                  "client_secret": "d0nt-T3ll"
+                }
+              }
+        required: true
+      responses:
+        "200":
+          description: The addition was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  submit_url:
+                    type: string
+                    format: uri
+                    description: |-
+                      An optional field containing a URL where the client must
+                      submit the validation token to, with identical parameters
+                      to the Identity Service API's `POST
+                      /validate/email/submitToken` endpoint (without the requirement
+                      for an access token). The homeserver must send this token to the
+                      user (if applicable), who should then be prompted to provide it
+                      to the client.
+
+                      If this field is not present, the client can assume that
+                      verification will happen without the client's involvement
+                      provided the homeserver advertises this specification version
+                      in the `/versions` response (ie: r0.5.0).
+                    example: https://example.org/path/to/submitToken
+              examples:
+                response:
+                  value: {
+                    "submit_url": "https://example.org/path/to/submitToken"
+                  }
+        "403":
+          description: The credentials could not be verified with the identity server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_AUTH_FAILED",
+                    "error": "The third-party credentials could not be verified by the identity server."
+                  }
+      tags:
+        - Account management
+  /account/3pid/add:
+    post:
+      summary: Adds contact information to the user's account.
+      description: |-
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        Adds contact information to the user's account. Homeservers should use 3PIDs added
+        through this endpoint for password resets instead of relying on the identity server.
+
+        Homeservers should prevent the caller from adding a 3PID to their account if it has
+        already been added to another user's account on the homeserver.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
+      operationId: add3PID
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      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
+                client_secret:
+                  type: string
+                  description: The client secret used in the session with the homeserver.
+                  example: d0nt-T3ll
+                sid:
+                  type: string
+                  description: The session identifier given by the homeserver.
+                  example: abc123987
+              required:
+                - client_secret
+                - sid
+        required: true
+      responses:
+        "200":
+          description: The addition was successful.
+          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/3pid/bind:
+    post:
+      summary: Binds a 3PID to the user's account through an Identity Service.
+      description: |-
+        Binds a 3PID to the user's account through the specified identity server.
+
+        Homeservers should not prevent this request from succeeding if another user
+        has bound the 3PID. Homeservers should simply proxy any errors received by
+        the identity server to the caller.
+
+        Homeservers should track successful binds so they can be unbound later.
+      operationId: bind3PID
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                client_secret:
+                  type: string
+                  description: The client secret used in the session with the identity server.
+                id_server:
+                  type: string
+                  description: The identity server to use.
+                id_access_token:
+                  type: string
+                  description: An access token previously registered with the identity server.
+                sid:
+                  type: string
+                  description: The session identifier given by the identity server.
+              required:
+                - client_secret
+                - id_server
+                - id_access_token
+                - sid
+              example: {
+                "id_server": "example.org",
+                "id_access_token": "abc123_OpaqueString",
+                "sid": "abc123987",
+                "client_secret": "d0nt-T3ll"
+              }
+        required: true
+      responses:
+        "200":
+          description: The addition was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+  /account/3pid/delete:
+    post:
+      summary: Deletes a third-party identifier from the user's account
+      description: |-
+        Removes a third-party identifier from the user's account. This might not
+        cause an unbind of the identifier from the identity server.
+
+        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.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+      operationId: delete3pidFromAccount
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id_server:
+                  type: string
+                  description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the `id_server` the identifier was added through. If the
+                    homeserver does not know the original `id_server`, it MUST return
+                    a `id_server_unbind_result` of `no-support`.
+                  example: example.org
+                medium:
+                  type: string
+                  description: The medium of the third-party identifier being removed.
+                  enum:
+                    - email
+                    - msisdn
+                  example: email
+                address:
+                  type: string
+                  description: The third-party address being removed.
+                  example: example@example.org
+              required:
+                - medium
+                - address
+        required: true
+      responses:
+        "200":
+          description: |-
+            The homeserver has disassociated the third-party identifier from the
+            user.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id_server_unbind_result:
+                    type: string
+                    enum:
+                      - no-support
+                      - success
+                    description: |-
+                      An indicator as to whether or not the homeserver was able to unbind
+                      the 3PID from the identity server. `success` indicates that the
+                      identity server has unbound the identifier whereas `no-support`
+                      indicates that the identity server refuses to support the request
+                      or the homeserver was not able to determine an identity server to
+                      unbind from.
+                    example: success
+                required:
+                  - id_server_unbind_result
+      tags:
+        - Account management
+  /account/3pid/unbind:
+    post:
+      summary: Removes a user's third-party identifier from an identity server.
+      description: |-
+        Removes a user's third-party identifier from the provided identity server
+        without removing it from the homeserver.
+
+        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.
+      operationId: unbind3pidFromAccount
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id_server:
+                  type: string
+                  description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the `id_server` the identifier was added through. If the
+                    homeserver does not know the original `id_server`, it MUST return
+                    a `id_server_unbind_result` of `no-support`.
+                  example: example.org
+                medium:
+                  type: string
+                  description: The medium of the third-party identifier being removed.
+                  enum:
+                    - email
+                    - msisdn
+                  example: email
+                address:
+                  type: string
+                  description: The third-party address being removed.
+                  example: example@example.org
+              required:
+                - medium
+                - address
+        required: true
+      responses:
+        "200":
+          description: |-
+            The identity server has disassociated the third-party identifier from the
+            user.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id_server_unbind_result:
+                    type: string
+                    enum:
+                      - no-support
+                      - success
+                    description: |-
+                      An indicator as to whether or not the identity server was able to unbind
+                      the 3PID. `success` indicates that the identity server has unbound the
+                      identifier whereas `no-support` indicates that the identity server
+                      refuses to support the request or the homeserver was not able to determine
+                      an identity server to unbind from.
+                    example: success
+                required:
+                  - id_server_unbind_result
+      tags:
+        - Account management
+  /account/3pid/email/requestToken:
+    post:
+      summary: Begins the validation process for an email address for association with
+        the user's account.
+      description: |-
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding an email address to an
+        account. This API's parameters and response are identical to that of
+        the [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
+        endpoint. The homeserver should validate
+        the email itself, either by sending a validation email itself or by using
+        a service it has control over.
+      operationId: requestTokenTo3PIDEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_email_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: |-
+            An email was sent to the given address. Note that this may be an
+            email containing the validation token or it may be informing the
+            user of an error.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The third-party identifier is already in use on the homeserver, or
+            the request was invalid. Error codes that can be returned are:
+              * `M_THREEPID_IN_USE`: The email supplied cannot be bound because is is already
+                associated with a different Matrix ID.
+              * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server
+                provided in the request.
+              * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding email addresses.
+              * `M_INVALID_PARAM`: The email address given was not valid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "Third-party identifier already in use"
+                  }
+        "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/3pid/msisdn/requestToken:
+    post:
+      summary: Begins the validation process for a phone number for association with
+        the user's account.
+      description: |-
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding a phone number to an
+        account. This API's parameters and response are identical to that of
+        the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
+        endpoint. 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: requestTokenTo3PIDMSISDN
+      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 third-party identifier is already in use on the homeserver, or
+            the request was invalid. Error codes that can be returned are:
+              * `M_THREEPID_IN_USE`: The phone number supplied cannot be bound because is is already
+                associated with a different Matrix ID.
+              * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server
+              * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding phone numbers.
+              * `M_INVALID_PARAM`: The phone number given was not valid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "Third-party identifier already in use"
+                  }
+        "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