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

# 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.
      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.
      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.
      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. 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_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. 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_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