# 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 additionalProperties: type: object additionalProperties: type: string 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: {}