Implement organization invitation
As a multi-organization application, one common requirement is to invite members to your organization. In this guide, we will walk you through the steps and technical details to implement this feature in your application.
Flow overviewโ
The overall process is illustrated in the diagram below:
Create organization rolesโ
Before inviting members to your organization, you need to create organization roles. Check out the Configure organizations guide for detailed instructions.
In this guide, let's create two typical organization roles: admin
and member
.
The admin
role has full access to all resources in the organization, while the member
role has limited access. For example, each role can have a set of permissions as follows:
admin
role:read:data
- Read access to all organization data resources.write:data
- Write access to all organization data resources.delete:data
- Delete access to all organization data resources.invite:member
- Invite members to the organization.manage:member
- Manage members in the organization.delete:member
- Remove members from the organization.
member
role:read:data
- Read access to all organization data resources.write:data
- Write access to all organization data resources.invite:member
- Invite members to the organization.
This can be done easily in the Logto Admin Console. You can also use the Logto Management API to create organization roles programmatically.
![organization roles](/assets/images/organization-roles-1492f03a077b3572daf6e60cd1835f3e.webp)
Configure your email connectorโ
Since invitations are sent via email, ensure your email connector is properly configured. To send invitations, you need to configure a newly introduced email template usage type - OrganizationInvitation
.
Logto Cloud's built-in "Logto email service" does not support the OrganizationInvitation
usage type at the moment. Instead, you need to configure your email connector (e.g. Sendgrid) and set up the OrganizationInvitation
template.
A sample email template for the OrganizationInvitation
usage type is shown below:
{
"subject": "Welcome to my organization",
"content": "<p>Join my organization by this <a href=\"{{link}}\" target=\"_blank\">link</a>.</p>",
"usageType": "OrganizationInvitation",
"type": "text/html"
}
The {{link}}
placeholder in the email content will be replaced with the actual invitation link when sending the email. In this guide, let's say it would be https://your-app.com/invitation/accept/{your-invitation-id}
.
You can check out the Configure popular email service guide for more details on setting up email connectors.
Handle invitations with Logto Management APIโ
If you haven't set up the Logto Management API yet, check out Interact with Management API for details.
We've provided a set of invitation-related Management APIs in the organizations feature. With these APIs, you can:
-
POST /api/organization-invitations
create an organization invitation with an assigned organization role. -
POST /api/organization-invitations/{id}/message
send the organization invitation to invitee via email.Note: This API payload supports a
link
property, you can compose your invitation link based on the invitation ID. For example:{
"link": "https://your-app.com/invitation/accept/{your-invitation-id}"
}Accordingly, you need to implement a landing page when your invitee navigates through the invitation link to your application.
-
GET /api/organization-invitations
&GET /api/organization-invitations/{id}
get all your invitations or a specific one by ID.On your landing page, use these APIs to list all invitations or details of an invitation that a user has received.
-
PUT /api/organization-invitations/{id}/status
accept or reject the invitation by updating the invitation status.Use this API to handle the user's response to the invitation.
Please be noted that all the APIs listed above requires a valid "organization access token". Check this guide to learn how to obtain the organization access token.
Use organization role-based access control (RBAC) to manage user permissionsโ
With the above setups, you can now send invitations via email, and invitees can join the organization with the assigned role.
Users with different organization roles will have different scopes (permissions) in their organization access tokens. Thus, both your client app and backend services should check these scopes to determine visible features and permitted actions.
Handle scope updates in access tokensโ
Managing scope updates in access tokens involves:
- Revoking existing scopes: For instance, demoting an admin to a non-admin member automatically shrinks scopes in the new access token obtained with the existing refresh token.
- Granting new scopes: Conversely, promoting a user to admin requires triggering a re-login or re-consent process to reflect the change in user access tokens.
Logto provides Management API to fetch real-time user permissions in the organization.
GET /api/organizations/{id}/users/{userId}/scopes
You can then compare the scopes in the user's access token with the real-time permissions to determine if the user has been promoted or demoted.
-
If promoted, trigger a re-login or re-consent process to update the user's access token. Let's take the React SDK for example:
const { clearAllTokens, signIn } = useLogto();
...
// If fetched real-time scopes have newly assigned scopes than the organization access token scopes
await clearAllTokens();
signIn({
redirectUri: '<your-sign-in-redirect-uri>',
prompt: 'consent',
});The above code will trigger a page navigation to the consent page and auto-redirect back to your app, with updated scopes in the user's organization access token.
-
If demoted, you can simply clear the cached access token and the SDK will automatically issue a new one with the updated scopes.
const { clearAccessToken } = useLogto();
...
// If fetched real-time scopes have fewer scopes than the organization access token scopes
await clearAccessToken();This does not require a re-login or re-consent process. New access tokens will be issued automatically by the Logto SDK.