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

# 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.
swagger: '2.0'
info:
  title: "Matrix Client-Server Account Administrative Contact API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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:
        - accessToken: []
      responses:
        200:
          description: The lookup was successful.
          examples:
            application/json: {
              "threepids": [
                {
                  "medium": "email",
                  "address": "monkey@banana.island",
                  "validated_at": 1535176800000,
                  "added_at": 1535336848756
                }
              ]
            }
          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']
      tags:
        - User data
    post:
      summary: Adds contact information to the user's account.
      description: Adds contact information to the user's account.
      operationId: post3PIDs
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          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"]
              bind:
                type: boolean
                description: |-
                  Whether the homeserver should also bind this third party
                  identifier to the account's Matrix ID with the passed identity
                  server. Default: ``false``.
                x-example: true
            required: ["three_pid_creds"]
            example: {
                "three_pid_creds": {
                  "id_server": "matrix.org",
                  "id_access_token": "abc123_OpaqueString",
                  "sid": "abc123987",
                  "client_secret": "d0n'tT3ll"
                },
                "bind": false
              }
      responses:
        200:
          description: The addition was successful.
          examples:
            application/json: {
              "submit_url": "https://example.org/path/to/submitToken"
            }
            schema:
              type: object
              properties:
                submit_url:
                  type: string
                  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. 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"
        403:
          description: The credentials could not be verified with the identity server.
          examples:
            application/json: {
                "errcode": "M_THREEPID_AUTH_FAILED",
                "error": "The third party credentials could not be verified by the identity server."
              }
          schema:
            "$ref": "definitions/errors/error.yaml"
      tags:
        - User data
  "/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:
        - accessToken: []
      parameters:
        - in: body
          name: body
          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']
      responses:
        200:
          description: |-
            The homeserver has disassociated the third party identifier from the
            user.
          schema:
            type: object
            properties:
              id_server_unbind_result:
                type: string
                enum:
                  # XXX: I don't know why, but the order matters here so that "no-support"
                  # doesn't become "no- support" by the renderer.
                  - "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
                  indentity 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:
        - User data
  "/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:
        - accessToken: []
      parameters:
        - in: body
          name: body
          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']
      responses:
        200:
          description: |-
            The identity server has disassociated the third party identifier from the
            user.
          schema:
            type: object
            properties:
              id_server_unbind_result:
                type: string
                enum:
                  # XXX: I don't know why, but the order matters here so that "no-support"
                  # doesn't become "no- support" by the renderer.
                  - "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:
        - User data
  "/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|_ endpoint. The homeserver has the
        choice of validating the email address itself, or proxying the request
        to the ``/validate/email/requestToken`` Identity Service API as
        identified by ``id_server``. It is imperative that the
        homeserver keep a list of trusted Identity Servers and only proxies to
        those that it trusts.
      operationId: requestTokenTo3PIDEmail
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: "./definitions/request_email_validation.yaml"
      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.
          schema:
            $ref: "definitions/request_token_response.yaml"
        403:
          description: |-
            The homeserver does not allow the third party identifier as a
            contact option.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_THREEPID_DENIED",
              "error": "Third party identifier is not allowed"
            }
        400:
          description: |-
            The third party identifier is already in use on the homeserver, or
            the request was invalid.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_THREEPID_IN_USE",
              "error": "Third party identifier already in use"
            }
  "/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|_ endpoint. The homeserver has the
        choice of validating the phone number itself, or proxying the request
        to the ``/validate/msisdn/requestToken`` Identity Service API as
        identified by ``id_server``. It is imperative that the
        homeserver keep a list of trusted Identity Servers and only proxies to
        those that it trusts.
      operationId: requestTokenTo3PIDMSISDN
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: "./definitions/request_msisdn_validation.yaml"
      responses:
        200:
          description: An SMS message was sent to the given phone number.
          schema:
            $ref: "definitions/request_token_response.yaml"
        403:
          description: |-
            The homeserver does not allow the third party identifier as a
            contact option.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_THREEPID_DENIED",
              "error": "Third party identifier is not allowed"
            }
        400:
          description: |-
            The third party identifier is already in use on the homeserver, or
            the request was invalid.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_THREEPID_IN_USE",
              "error": "Third party identifier already in use"
            }