matrix-spec/data/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.
openapi: 3.1.0
info:
  title: Matrix Federation Third-party Invites API
  version: 1.0.0
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](/server-server-api/#inviting-to-a-room) section before returning a
        response to this request.
      operationId: exchangeThirdPartyInvite
      security:
        - signedRequest: []
      parameters:
        - in: path
          name: roomId
          description: The room ID to exchange a third-party invite in
          required: true
          example: "!abc123:matrix.org"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            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
                              additionalProperties:
                                type: object
                                additionalProperties:
                                  type: string
                              description: |-
                                The server signatures for this event.

                                The signature is calculated using the process
                                described at [Signing JSON](/appendices/#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"
                      }
                    }
                  }
                }
              }
            }
        description: A partial `m.room.member` event
        required: true
      responses:
        "200":
          description: The invite has been issued successfully.
          content:
            application/json:
              schema:
                type: object
                description: An empty object
                example: {}
              examples:
                response:
                  value: {}
  /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
      requestBody:
        content:
          application/json:
            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
        required: true
      responses:
        "200":
          description: The homeserver has processed the notification.
          content:
            application/json:
              schema:
                type: object
                description: An empty object
                example: {}
              examples:
                response:
                  value: {}
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8448
      basePath:
        default: /_matrix/federation/v1
components:
  securitySchemes:
    signedRequest:
      $ref: definitions/security.yaml#/signedRequest