Specify remote invite

specification/server_server_api.rst

@@ -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