matrix-spec/data/api/identity/v2_associations.yaml

# Copyright 2018 New Vector 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 Identity Service Establishing Associations API
  version: 2.0.0
paths:
  /3pid/getValidated3pid:
    get:
      summary: Check whether ownership of a 3pid was validated.
      description: Determines if a given 3pid has been validated by a user.
      operationId: getValidated3pidV2
      security:
        - accessToken: []
      parameters:
        - in: query
          name: sid
          description: The Session ID generated by the `requestToken` call.
          required: true
          example: "1234"
          schema:
            type: string
        - in: query
          name: client_secret
          description: The client secret passed to the `requestToken` call.
          required: true
          example: monkeys_are_GREAT
          schema:
            type: string
      responses:
        "200":
          description: Validation information for the session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  medium:
                    type: string
                    description: The medium type of the 3pid.
                  address:
                    type: string
                    description: The address of the 3pid being looked up.
                  validated_at:
                    type: integer
                    format: int64
                    description: |-
                      Timestamp, in milliseconds, indicating the time that the 3pid
                      was validated.
                required:
                  - medium
                  - address
                  - validated_at
              examples:
                response:
                  value: {
                    "medium": "email",
                    "validated_at": 1457622739026,
                    "address": "louise@bobs.burgers"
                  }
        "400":
          description: |-
            The session has not been validated.

            If the session has not been validated, then `errcode` will be
            `M_SESSION_NOT_VALIDATED`.  If the session has timed out, then
            `errcode` will be `M_SESSION_EXPIRED`.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_SESSION_NOT_VALIDATED",
                    "error": "This validation session has not yet been completed"
                  }
        "403":
          description: |
            The user must do something in order to use this endpoint. One example
            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_TERMS_NOT_SIGNED",
                    "error": "Please accept our updated terms of service before continuing"
                  }
        "404":
          description: The Session ID or client secret were not found.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NO_VALID_SESSION",
                    "error": "No valid session was found matching that sid and client secret"
                  }
  /3pid/bind:
    post:
      summary: Publish an association between a session and a Matrix user ID.
      description: |-
        Publish an association between a session and a Matrix user ID.

        Future calls to `/lookup` for any of the session\'s 3pids will return
        this association.

        Note: for backwards compatibility with previous drafts of this
        specification, the parameters may also be specified as
        `application/x-form-www-urlencoded` data.  However, this usage is
        deprecated.
      operationId: bindV2
      security:
        - accessToken: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "sid": "1234",
                "client_secret": "monkeys_are_GREAT",
                "mxid": "@ears:matrix.org"
              }
              properties:
                sid:
                  type: string
                  description: The Session ID generated by the `requestToken` call.
                client_secret:
                  type: string
                  description: The client secret passed to the `requestToken` call.
                mxid:
                  type: string
                  description: The Matrix user ID to associate with the 3pids.
              required:
                - sid
                - client_secret
                - mxid
      responses:
        "200":
          description: The association was published.
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                    description: The 3pid address of the user being looked up.
                  medium:
                    type: string
                    description: The medium type of the 3pid.
                  mxid:
                    type: string
                    description: The Matrix user ID associated with the 3pid.
                  not_before:
                    type: integer
                    format: int64
                    description: A unix timestamp before which the association is not known to be
                      valid.
                  not_after:
                    type: integer
                    format: int64
                    description: A unix timestamp after which the association is not known to be
                      valid.
                  ts:
                    type: integer
                    format: int64
                    description: The unix timestamp at which the association was verified.
                  signatures:
                    type: object
                    description: |-
                      The signatures of the verifying identity servers which show that the
                      association should be trusted, if you trust the verifying identity
                      services.
                    allOf:
                      - $ref: ../../schemas/server-signatures.yaml
                required:
                  - address
                  - medium
                  - mxid
                  - not_before
                  - not_after
                  - ts
                  - signatures
              examples:
                response:
                  value: {
                    "address": "louise@bobs.burgers",
                    "medium": "email",
                    "mxid": "@ears:matrix.org",
                    "not_before": 1428825849161,
                    "not_after": 4582425849161,
                    "ts": 1428825849161,
                    "signatures": {
                      "matrix.org": {
                        "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
                      }
                    }
                  }
        "400":
          description: |-
            The association was not published.

            If the session has not been validated, then `errcode` will be
            `M_SESSION_NOT_VALIDATED`.  If the session has timed out, then
            `errcode` will be `M_SESSION_EXPIRED`.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_SESSION_NOT_VALIDATED",
                    "error": "This validation session has not yet been completed"
                  }
        "403":
          description: |
            The user must do something in order to use this endpoint. One example
            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_TERMS_NOT_SIGNED",
                    "error": "Please accept our updated terms of service before continuing"
                  }
        "404":
          description: The Session ID or client secret were not found
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NO_VALID_SESSION",
                    "error": "No valid session was found matching that sid and client secret"
                  }
  /3pid/unbind:
    post:
      summary: Remove an association between a session and a Matrix user ID.
      description: |-
        Remove an association between a session and a Matrix user ID.

        Future calls to `/lookup` for any of the session's 3pids will not
        return the removed association.

        The identity server should authenticate the request in one of two
        ways:

        1. The request is signed by the homeserver which controls the `user_id`.
        2. The request includes the `sid` and `client_secret` parameters,
           as per `/3pid/bind`, which proves ownership of the 3PID.

        If this endpoint returns a JSON Matrix error, that error should be passed
        through to the client requesting an unbind through a homeserver, if the
        homeserver is acting on behalf of a client.
      operationId: unbindV2
      security:
        - accessToken: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "sid": "1234",
                "client_secret": "monkeys_are_GREAT",
                "mxid": "@ears:example.org",
                "threepid": {
                  "medium": "email",
                  "address": "monkeys_have_ears@example.org"
                }
              }
              properties:
                sid:
                  type: string
                  description: The Session ID generated by the `requestToken` call.
                client_secret:
                  type: string
                  description: The client secret passed to the `requestToken` call.
                mxid:
                  type: string
                  description: The Matrix user ID to remove from the 3pids.
                threepid:
                  type: object
                  title: 3PID
                  description: |-
                    The 3PID to remove. Must match the 3PID used to generate the session
                    if using `sid` and `client_secret` to authenticate this request.
                  properties:
                    medium:
                      type: string
                      description: |-
                        A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
                        of the identifier to unbind.
                    address:
                      type: string
                      description: The 3PID address to remove.
                  required:
                    - medium
                    - address
              required:
                - threepid
                - mxid
      responses:
        "200":
          description: The association was successfully removed.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
        "400":
          description: |-
            If the response body is not a JSON Matrix error, the identity server
            does not support unbinds. If a JSON Matrix error is in the response
            body, the requesting party should respect the error.
        "403":
          description: |-
            The credentials supplied to authenticate the request were invalid.
            This may also be returned if the identity server does not support
            the chosen authentication method (such as blocking homeservers from
            unbinding identifiers).

            Another common error code is `M_TERMS_NOT_SIGNED` where the user
            needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN",
                    "error": "Invalid homeserver signature"
                  }
        "404":
          description: |-
            If the response body is not a JSON Matrix error, the identity server
            does not support unbinds. If a JSON Matrix error is in the response
            body, the requesting party should respect the error.
        "501":
          description: |-
            If the response body is not a JSON Matrix error, the identity server
            does not support unbinds. If a JSON Matrix error is in the response
            body, the requesting party should respect the error.
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8090
      basePath:
        default: /_matrix/identity/v2
components:
  securitySchemes:
    $ref: definitions/security.yaml