Invite organization members
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 organization template 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 Console. You can also use the Logto Management API to create organization roles programmatically.
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
.
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}
.
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.
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 alink
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 token". Check this guide to learn how to obtain the organization 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 tokens. Thus, both your client app and backend services should check these scopes to determine visible features and permitted actions.
Handle scope updates in organization tokens
Make sure you have integrated organization with your app. Check out the integration guide for more details.
Managing scope updates in organization tokens involves:
Revoking existing scopes
For instance, demoting an admin to a non-admin member should remove scopes from the user. In such case, you can simply clear the cached organization token and fetch a new one with refresh token. The shrunk scopes will be reflected immediately in the newly issued organization token.
Granting new scopes
This can be further divided into two scenarios:
Grant new scopes that already defined in your auth system
Similar to revoking scopes, if the newly granted scope is already registered with the auth server, you can simply issue a new organization token, and the new scopes will be reflected immediately.
Grant new scopes that are newly introduced your auth system
In this case, you need to trigger a re-login or re-consent process to update the user's organization token. E.g., calling the signIn
method in Logto SDK.
Learn more about issuing an organization token.
Implement real-time permission check and update organization token
Logto provides Management API to fetch real-time user permissions in the organization.
GET /api/organizations/{id}/users/{userId}/scopes
(API references)
You can then compare the scopes in the user's organization token with the real-time permissions to determine if the user has been promoted or demoted.
-
If demoted, you can simply clear the cached organization 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 token scopes
await clearAccessToken();This does not require a re-login or re-consent process. New organization tokens will be issued automatically by the Logto SDK.
-
If new scope is introduced into your auth system, trigger a re-login or re-consent process to update the user's organization 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 token scopes
await clearAllTokens();
signIn({
redirectUri: '<your-sign-in-redirect-uri>',
prompt: 'consent',
});The above code will trigger a page navigation to the consent screen and auto-redirect back to your app, with updated scopes in the user's organization token.
Related resources
How we implement user collaboration within a multi-tenant app