matrix-spec/api/server-server/third_party_invite.yaml

# Copyright 2018 New Vector 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 Federation Third Party Invites API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/exchange_third_party_invite/{roomId}":
    put:
      summary: Request a server to auth a third party invite event
      description: |-
        The receiving server will verify the partial ``m.room.member`` event
        given in the request body. If valid, the receiving server will issue
        an invite as per the `Inviting to a room`_ section before returning a
        response to this request.
      operationId: exchangeThirdPartyInvite
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: roomId
          type: string
          description: The room ID to exchange a third party invite in
          required: true
          x-example: "!abc123:matrix.org"
        - in: body
          name: body
          type: object
          description: A partial ``m.room.member`` event
          required: true
          schema:
            type: object
            properties:
              type:
                type: string
                description: The event type. Must be ``m.room.member``
                example: "m.room.member"
              room_id:
                type: string
                description: |-
                  The room ID the event is for. Must match the ID given in
                  the path.
                example: "!abc123:matrix.org"
              sender:
                type: string
                description: |-
                  The user ID of the user who sent the original ``m.room.third_party_invite``
                  event.
                example: "@joe:matrix.org"
              state_key:
                type: string
                description: The user ID of the invited user
                example: "@someone:example.org"
              content:
                type: object
                description: The event content
                title: Event Content
                properties:
                  membership:
                    type: string
                    description: The membership state. Must be ``invite``
                    example: invite
                  third_party_invite:
                    type: object
                    description: The third party invite
                    title: Third Party Invite
                    properties:
                      display_name:
                        type: string
                        description: |-
                          A name which can be displayed to represent the user instead of their
                          third party identifier.
                        example: "alice"
                      signed:
                        type: object
                        description: |-
                          A block of content which has been signed, which servers can use to
                          verify the event.
                        title: Invite Signatures
                        properties:
                          signatures:
                            type: object
                            title: Signatures
                            description: |-
                              The server signatures for this event.

                              The signature is calculated using the process
                              described at `Signing JSON`_.
                            example: {
                              "magic.forest": {
                                "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                              }
                            }
                          mxid:
                            type: string
                            description: The invited matrix user ID
                            example: "@alice:localhost"
                          token:
                            type: string
                            description: The token used to verify the event
                            example: abc123
                        required: ['signatures', 'mxid', 'token']
                        example: {
                          "mxid": "@alice:localhost",
                          "token": "abc123",
                          "signatures": {
                            "magic.forest": {
                              "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                            }
                          }
                        }
                    required: ['display_name', 'signed']
                    example: {
                      "display_name": "alice",
                      "signed": {
                        "mxid": "@alice:localhost",
                        "token": "abc123",
                        "signatures": {
                          "magic.forest": {
                            "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                          }
                        }
                      }
                    }
                required: ['membership', 'third_party_invite']
                example: {
                  "membership": "invite",
                  "third_party_invite": {
                    "display_name": "alice",
                    "signed": {
                      "mxid": "@alice:localhost",
                      "token": "abc123",
                      "signatures": {
                        "magic.forest": {
                          "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                        }
                      }
                    }
                  }
                }
            required:
              - type
              - room_id
              - sender
              - state_key
              - content
          example: {
            "type": "m.room.member",
            "room_id": "!abc123:matrix.org",
            "sender": "@joe:matrix.org",
            "state_key": "@someone:example.org",
            "content": {
              "membership": "invite",
              "third_party_invite": {
                "display_name": "alice",
                "signed": {
                  "mxid": "@alice:localhost",
                  "token": "abc123",
                  "signatures": {
                    "magic.forest": {
                      "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                    }
                  }
                }
              }
            }
          }
      responses:
        200:
          description: The invite has been issued successfully.
          examples:
            application/json: {}
          schema:
            type: object
            description: An empty object
            example: {}
  "/3pid/onbind":
    put:
      summary: |-
        Notifies the server that a third party identifier has been bound to one
        of its users.
      description: |-
        Used by identity servers to notify the homeserver that one of its users
        has bound a third party identifier successfully, including any pending
        room invites the identity server has been made aware of.
      operationId: onBindThirdPartyIdentifier
      parameters:
        - in: body
          name: body
          type: object
          required: true
          schema:
            type: object
            properties:
              medium:
                type: string
                description: |-
                  The type of third party identifier. Currently only "email" is
                  a possible value.
                example: "email"
              address:
                type: string
                description: |-
                  The third party identifier itself. For example, an email address.
                example: "alice@example.com"
              mxid:
                type: string
                description: The user that is now bound to the third party identifier.
                example: "@alice:matrix.org"
              invites:
                type: array
                description: |-
                  A list of pending invites that the third party identifier has received.
                items:
                  type: object
                  title: Third Party Invite
                  properties:
                    medium:
                      type: string
                      description: |-
                        The type of third party invite issues. Currently only
                        "email" is used.
                      example: "email"
                    address:
                      type: string
                      description: |-
                        The third party identifier that received the invite.
                      example: "alice@example.com"
                    mxid:
                      type: string
                      description: The now-bound user ID that received the invite.
                      example: "@alice:matrix.org"
                    room_id:
                      type: string
                      description: The room ID the invite is valid for.
                      example: "!somewhere:example.org"
                    sender:
                      type: string
                      description: The user ID that sent the invite.
                      example: "@bob:matrix.org"
                    # TODO (TravisR): Make this reusable when doing IS spec changes
                    #   also make sure it isn't lying about anything, like the key version
                    signed:
                      type: object
                      title: Identity Server Signatures
                      description: |-
                        Signature from the identity server using a long-term private
                        key.
                      properties:
                        mxid:
                          type: string
                          description: |-
                            The user ID that has been bound to the third party
                            identifier.
                          example: "@alice:matrix.org"
                        token:
                          type: string
                          # TODO: What is this actually?
                          description: A token.
                          example: "Hello World"
                        signatures:
                          type: object
                          title: Identity Server Signature
                          description: |-
                            The signature from the identity server. The ``string`` key
                            is the identity server's domain name, such as vector.im
                          additionalProperties:
                            type: object
                            title: Identity Server Domain Signature
                            description: The signature for the identity server.
                            properties:
                              "ed25519:0":
                                type: string
                                description: The signature.
                                example: "SomeSignatureGoesHere"
                            required: ['ed25519:0']
                          example: {
                            "vector.im": {
                              "ed25519:0": "SomeSignatureGoesHere"
                            }
                          }
                      required: ['mxid', 'token', 'signatures']
                  required:
                    - medium
                    - address
                    - mxid
                    - room_id
                    - sender
                    - signed
            required: ['medium', 'address', 'mxid', 'invites']
      responses:
        200:
          description: The homeserver has processed the notification.
          examples:
            application/json: {}
          schema:
            type: object
            description: An empty object
            example: {}