Check for invitations during registration
When someone signs up for your service directly, without coming in via an invitation link, it’s still important to check for open invitations to make sure that the user ends up in an existing organization instead of unnecessarily creating a new one. This is a very common problem with B2B SaaS services, especially ones where content can be shared with unregistered people. Let’s use Slack as an example. Say [email protected] has been invited to three different Slack workspaces. For whatever reason, Bob doesn’t use any of the invitations he received, and instead goes directly to slack.com to sign up. As soon as his email address has been confirmed, Slack presents Bob with the three workspaces that he can join, as well as an option to create a new workspace. This flow would look something like this:Check for open invitations
Send a GET request to
/invitations with targetType being “email” and targetValue being the email address used at registration. This will return a list of open invitations to the given email address. If there are any organizations that can be joined via autojoin (i.e., based on the email domain) they will also be included in the response.Present invitations to the user (optional)
If any additional invitations were returned, it’s up to you to decide what to do with them based on the nature of your service. In the previous Slack example, the user can select just one workspace to join at a time, which makes sense because each workspace on Slack requires its own set of credentials. For some services, allowing the user to select multiple invitations to accept at once may make sense. And for others, you might want to simply have all open invitations accepted automatically upon registration. For example, if you’re invited to join multiple boards on Trello, when you sign up you’re automatically a member of all of those boards.
Mark the invitation(s) as accepted
If any invitations were presented and accepted, once the user completes the signup process, send a POST request
/invitations/accept with the IDs of the invitations being accepted.In-product invitation acceptance
Invitations to join your service are obviously not the extent of the invitations that may be relevant to you. Even once a user has signed up, depending on the nature of your service, they may get invited to join boards or documents, or to connect with other users. Or there may still be additional open invitations from before they signed up. Either way, if you want to have an in-product invitation acceptance experience…Check for open invitations
Send a GET request to
/invitations with targetType being “email” and targetValue being the email address of the given user.Present invitations to the user
Provide a UX for the user to select one or more invitations to accept.
Mark the invitation(s) as accepted
Send a POST request to
/invitations/accept with the IDs of the selected invitations.Displaying a list of open invitations
You might want to display a list of open invitations on the Members page of a workspace, or in an admin area, of a B2B service, or on a user’s Connections page in a community site. To get a list of all open invitations, send a GET request to/invitations/by-group/{groupType}/{groupId} where groupType is the type of grouping (e.g., workspace, org, etc.) and groupID is its internal ID.
Revoking an invitation
As part of displaying a list of open invitations, as described above, you may want to include a link or button to revoke/delete an invitation. Often this capability is limited to an admin, or possibly the user that generated the invitation. That link should send a DELETE request to the/invitations/{invitationId} endpoint to delete the given invitation.
Resending an invitation
Also as part of displaying a list of open invitations you may want to include a link or button to resend the invitation. Send a POST request to/invitations/{invitationId}/reinvite using the invitationId associated with the invitation being resent.
Autojoin administration
As mentioned in the overview of Autojoin, you’ll want to provide an interface for admins in your customer organizations to manage their list of allowed domains. They should be able to add or remove domains as needed. Below is one example of how this might be implemented.
/api/v1/invitations/autojoin endpoint (or use the corresponding method in one of our SDKs) to send the updated list of domains to Vortex. Note that this call will fail with a 400 response if any of the domains are webmail.