| Table of Contents |
|---|
...
Option 2 - Support all use cases except C2 and D2.
This option essentially restricts Bob to accepting the invitation with a Synapse account that is associated with the email address to which the invitation was sent.
Pros
- Better user experience, as Bob will only need to validate his email address once.
Cons
- Restricts Bob's choices.
The following content, colored in gray, is outdated.
Models to implement
| EmailInvitation | MembershipInvtnSignedToken |
|---|---|
emailAddress teamId | emailAddress inviterId teamId hmac |
Related models: AccountSetupInfo, MembershipInvtnSubmission
Services to implement
| Action | Intended User | URI | Method | Request Parameters | Request Body | Response Body | Success Response Code | Notification Sent to | Notes |
|---|---|---|---|---|---|---|---|---|---|
| Send email invitation with link to join a team | team administrator | /emailInvitation | POST | EmailInvitation | 200 OK | Email address provided | The invitation link will contain a serialized MembershipInvtnSignedToken | ||
| Create MembershipInvitation using a signed token | authorized user | /tokenMembershipInvitation | POST | inviteeId | MembershipInvtnSignedToken | MembershipInvtnSubmission | 201 Created | Similar to POST /membershipInvitation, but using a signed token for authorization. Also, doesn't send any email notifications. |
Related services: POST /principal/available, POST /account, POST /session, POST /membershipInvitation
Example implementation with Synapse web client
As the use cases above, the inviter is Alice and the invitee is Bob.
- Alice invites Bob to her team by entering his email address.
- Web client constructs an EmailInvitation using Bob's email address and Alice's team's id, then uses it to send a POST /emailInvitation request to the backend.
- Backend constructs a signed MembershipInvtnSignedToken with Bob's email address, Alice's team's id and Alice's id.
- Backend serializes the MembershipInvtnSignedToken, embeds it into an invitation link to the web client and sends the link to Bob's email address.
- Bob clicks on the link and does one of the following:
- Registers a new Synapse account.
- Web client constructs an AccountSetupInfo [1], then uses it to create Bob's account through POST /account and receives a session token.
- Signs in to his existing Synapse account.
- Web client retrieves a session token through POST /session.
- Registers a new Synapse account.
- Web client deserializes and validates the MembershipInvtnSignedToken in the link and extracts the inviteeId out of Bob's session token, then sends a POST /tokenMembershipInvitation request to the backend.
- Backend validates the MembershipInvtnSignedToken and inviteeId and creates a MembershipInvitation from Alice's team to Bob's account.
- Web client receives backend's 201 response, then directs Bob to his profile's Team tab, where he has a pending MembershipInvitation to Alice's team
- Bob accepts Alice's invitation (using the existing MembershipInvitation services).
[1] Note that the web client needs to construct a valid emailValidationToken, making up a timestamp in the process.Anchor 1 1
Alternative implementations
| Description | Pros | Cons | |
|---|---|---|---|
| 1 | POST /emailInvitation and POST /tokenMembershipInvitation (Proposal described above) | + Supports most use cases (all but B) + Simple -> less development time | - Not RESTful |
| 2 | Same as option 1, but store EmailInvitation in the database and implement REST methods for it. I.e. GET /emailInvitation, GET /emailInvitation/{id}, DELETE /emailInvitation/{id}, etc. | + Supports use case B + RESTful | - More complex -> more development time |
| 3 | + Supports use case B + More easily extensible (future support for operations other than inviting to a team) + RESTful | - Even more complex -> more development time - ACL management is out of scope |