Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-31 00:14:09 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Clarify CS API third party invites explanations and add more cross-API links

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2025-02-22 16:45:45 +01:00
parent cb83c5a76e
commit abb5d74a31
No known key found for this signature in database
GPG key ID: 0C971D9DBC9D678D
1 changed files with 25 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
content/client-server-api/modules/third_party_invites.md
View file

@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
their Matrix user ID is not known, instead addressing them by a third-party their Matrix user ID is not known, instead addressing them by a third-party
identifier such as an email address. There are two flows here; one identifier such as an email address. There are two flows here; one
if a Matrix user ID is known for the third-party identifier, and one if if a Matrix user ID is known for the third-party identifier, and one if
not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
third-party identifier. with the details of the third-party identifier.
The homeserver asks the identity server whether a Matrix user ID is The homeserver asks the identity server whether a Matrix user ID is
known for that identifier: known for that identifier:
@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
#### Server behaviour #### Server behaviour
Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
third-party identifier with the provided identity server. If the lookup the server is expected to look up the third-party identifier with the provided
yields a result for a Matrix User ID then the normal invite process can identity server byt making a call to [`/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
be initiated. This process ends up looking like this: If the lookup yields a result for a Matrix User ID then the normal [invite
process](/server-server-api/#inviting-to-a-room) can be initiated. This process
ends up looking like this:
``` ```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -66,10 +68,10 @@ be initiated. This process ends up looking like this:
| | | | | |
``` ```
However, if the lookup does not yield a bound User ID, the homeserver However, if the lookup does not yield a bound User ID, the homeserver must store
must store the invite on the identity server and emit a valid the invite on the identity server with a call to [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
`m.room.third_party_invite` event to the room. This process ends up and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
looking like this: to the room. This process ends up looking like this:
``` ```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -101,15 +103,18 @@ looking like this:
| | | | | |
``` ```
All homeservers MUST verify the signature in the event's The third-party user will then need to verify their identity, which results in a
`content.third_party_invite.signed` object. request to [`/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
from the identity server to the homeserver that bound the third-party identifier
to a user. The homeserver then exchanges the `m.room.third_party_invite` event
in the room for a complete `m.room.member` event with
`content.membership: invite` and a `content.third_party_invite` property for the
user that has bound the third-party identifier. If the invitee is on a different
homeserver than the inviting user, the invitee's homeserver makes a request to
[`/exchange_third_party_invite`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
The third-party user will then need to verify their identity, which All homeservers MUST verify the signature in the `m.room.member` event's
results in a call from the identity server to the homeserver that bound `content.third_party_invite.signed` object.
the third-party identifier to a user. The homeserver then exchanges the
`m.room.third_party_invite` event in the room for a complete
`m.room.member` event for `membership: invite` for the user that has
bound the third-party identifier.
If a homeserver is joining a room for the first time because of an If a homeserver is joining a room for the first time because of an
`m.room.third_party_invite`, the server which is already participating `m.room.third_party_invite`, the server which is already participating
@ -193,8 +198,8 @@ at any time - the completion is not shown in the diagram.
H1 MUST verify the request from H3 to ensure the `signed` property is H1 MUST verify the request from H3 to ensure the `signed` property is
correct as well as the `key_validity_url` as still being valid. This is correct as well as the `key_validity_url` as still being valid. This is
done by making a request to the [identity server done by making a request to the identity server's
/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid) [`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
endpoint, using the provided URL rather than constructing a new one. The endpoint, using the provided URL rather than constructing a new one. The
query string and response for the provided URL must match the Identity query string and response for the provided URL must match the Identity
Service Specification. Service Specification.