Specify remote invite
@@ -749,6 +749,64 @@ that requested by the requestor in the ``v`` parameter).
Specify (or remark that it is unspecified) how the server handles divergent
history. DFS? BFS? Anything weirder?
+Inviting to a room
+------------------
+
+When a user wishes to invite an other user to a local room and this other user
+is on a different server, the inviting server will send a request to the invited
+server::
+
+ PUT .../invite/{roomId}/{eventId}
+
+The required fields in the JSON body are:
+
+==================== ======== ============
+ Key Type Description
+==================== ======== ============
+``room_id`` String The room ID of the room. Must be the same as the
+ room ID specified in the path.
+``event_id`` String The ID of the event. Must be the same as the event
+ ID specified in the path.
+``type`` String The value ``m.room.member``.
+``auth_events`` List An event-reference list containing the IDs of the
+ authorization events that would allow this member
+ to be invited in the room.
+``content`` Object The content of the event.
+``depth`` Integer The depth of the event.
+``origin`` String The name of the inviting homeserver.
+``origin_server_ts`` Integer A timestamp added by the inviting homeserver.
+``prev_events`` List An event-reference list containing the IDs of the
+ immediate predecessor events.
+``sender`` String The Matrix ID of the user who sent the original
+ `m.room.third_party_invite`.
+``state_key`` String The Matrix ID of the invited user.
+``signatures`` Object The signature of the event from the origin server.
+``unsigned`` Object An object containing the properties that aren't
+ part of the signature's computation.
+==================== ======== ============
+
+Where the ``content`` key contains the content for the ``m.room.member`` event
+specified in the `Client-Server API`_. Note that the ``membership`` property of
+the content must be ``invite``.
+
+Upon receiving this request, the invited homeserver will append its signature to
+the event and respond to the request with the following JSON body::
+
+ [
+ 200,
+ "event": {...}
+ ]
+
+Where ``event`` contains the event signed by both homeservers, using the same
+JSON keys as the initial request on ``/invite/{roomId}/{eventId}``. Note that,
+except for the ``signatures`` object (which now contains an additional signature),
+all of the event's keys remain the same as in the event initially provided.
+
+This response format is due to a typo in Synapse, the first implementation of
+Matrix's APIs, and is preserved to maintain compatibility.
+
+Now that the event has been signed by both the inviting homeserver and the
+invited homeserver, it can be sent to all of the users in the room.
Authentication
--------------
@@ -1143,5 +1201,8 @@ that are too long.
[[TODO(markjh) We might want to allow the server to omit the output of well
known hash functions like SHA-256 when none of the keys have been redacted]]
+
+.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
+.. _`Client-Server API`: ../client_server/unstable.html#m-room-member
.. _`Canonical JSON`: ../appendices.html#canonical-json
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
