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

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:
  accessToken:
    type: apiKey
    description: The user_id or application service access_token
    name: access_token
    in: query
paths:
  "/account/password":
    post:
      summary: Changes a user's password.
      description: |-
        This API endpoint uses the 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.        
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: |-
              {
                "new_password": "ihatebananas"
              }              
            properties:
              new_password:
                type: string
                description: The new password for the account.
            required: ["new_password"]
      responses:
        200:
          description: The password has been changed.
          examples:
            application/json: "{}"
          schema:
            type: object
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/error.yaml"
      tags:
        - User data
  "/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.        
      security:
        - accessToken: []
      responses:
        200:
          description: The lookup was successful.
          examples:
            application/json: |-
              {
                "threepids": [
                  {
                    "medium": "email",
                    "address": "monkey@banana.island"
                  }
                ]
              }              
          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"]
                    address:
                      type: string
                      description: The third party identifier address.
      tags:
        - User data
    post:
      summary: Adds contact information to the user's account.
      description: Adds contact information to the user's account.
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              threePidCreds:
                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.
                  sid:
                    type: string
                    description: The session identifier given by the Identity Server.
                required: ["client_secret", "id_server", "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: ["threePidCreds"]
            example: |-
              {
                "threePidCreds": {
                  "id_server": "matrix.org",
                  "sid": "abc123987",
                  "client_secret": "d0n'tT3ll"
                },
                "bind": false
              }              
      responses:
        200:
          description: The addition was successful.
          examples:
            application/json: "{}"
            schema:
              type: object
        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."
              }              
      tags:
        - User data