Building a multi-tenant application with robust permissions can be tricky.

Clerk Organizations were designed to simplify adding multi-tenant functionality to your application. By implementing Organizations, your users will be empowered to create isolated areas of your application, while also allowing users to have granular permissions based on their assigned roles, restricting or permitting functionality as needed.

In this article, we'll take leverage the common example of a to-do app and implement Clerk Organizations to enable users to access task lists that are shared across teams.

Project overview and setup

This guide uses an open-source starter project that you can clone to your computer to build on.

The project is a multi-tenant take on a simple concept; a task management app. Upon setting up the project, you'll have a functional to-do app where you can add, complete, and update tasks. Throughout this guide, you'll add the ability to create and switch between organizations, where each organization has an isolated list of tasks where multiple users can be invited into for collaboration.

Clone the project locally

To follow this guide, open your terminal and clone the starter repository using the following script. This will also switch you to the article-1 branch which contains the proper starting point for this article:

Set up a Clerk project

If you do not have a Clerk account, create one before proceeding, which will walk you through creating a project. If you already have an account, create a new project for this guide. Give the project a name and accept the default login providers: Email and Google.

You'll be presented with a Next.js quick start guide. Follow only step 2, which instructs you to create the .env.local file and populate it with the necessary environment variables. The remainder of the steps are already completed as part of the starter repo.

Set up a Neon database

While any Postgres database should be usable, this guide leverages Neon. If you do not have an account, create one at neon.tech. If you do, create an empty database, copy the connection string from the “Connection Details” block, and add it to your .env.local file as DATABASE_URL like so:

Access the project

Back on your computer, start the project with the following command:

By default, the application will be accessible at http://localhost:3000 however the port might be different if another process is using port 3000, so use what's shown in the terminal. Accessing the URL from your browser should prompt you to create an account using Clerk before rendering this:

Feel free to test it out by adding a few tasks.

Enable Clerk Organizations

Now that you understand the project and the current state it's in, let's start by setting up the Organizations feature in Clerk.

Log into the Clerk Dashboard and select "Organization Settings" from the left navigation. In the settings tab, click the toggle next to "Enable organizations" if it's not on already.

From now on, users within this Clerk application will be able to create organizations and invite other users to them. This setting is configurable on this same page. Make sure to leave the default checked for the remainder of this guide.

Update the code

Now that Clerk Organizations are set up, we need to update the project to enable users to create organizations, switch between them, and create tasks specifically for that organization.

Start by adding the OrganizationSwitcher to the Navbar component:

The application should update to show “Personal account” next to your avatar in the upper right. This essentially indicates that the user does not have an organization selected that they are working in.

This same menu gives you the ability to create an organization, however, the database queries will need to be modified to recognize that the user is in an organization, so let's get those updated now.

The auth() function, part of Clerk's Next.js SDK, returns token claims for the current user stored in sessionClaims. These claims can be used to determine if an organization is selected along with the permissions the user has set for that specific organization. By default the org_id value of the claims is not set unless the user has an organization selected, indicating they are in the “Personal account”.

The following is what sessionClaims looks like with an organization selected:

Currently, the getUserInfo function in src/app/actions.ts uses the auth() function to return the user's ID from the claims, which is used as the owner_id in the database for a given task. The following snippet shows getUserInfo updated to conditionally return org_id if it is populated and how it is used in the database queries.

Note however that userId is still being used to maintain a record of who creates specific tasks, regardless if an organization is set or not.

Test Organization lists

To test the changes, use the Organization Switcher from the navigation bar and create a new organization.

Now let's invite another user into the organization to demonstrate how the tasks in the organization are shared, but the “Personal account” tasks are isolated between users.

If you are in the “Personal account” still, use the switcher to select the organization you created. Once active, use the switcher again and click the gear icon next to the organization name. Then select Members from the left navigation in the modal, and finally click the “Invite” button. Invite another user via their email address.

The user should receive an email with an invitation to the organization. Accept the invitation and create an account with the application. Upon completing the sign-up process, you should be dropped into the “Personal account” of the new user, which will have a blank list of tasks.

Now use the Organization Switcher to select your organization to see the tasks created by the previous user.

Adding additional tasks will show them for all users that have access to this organization.

Conclusion

Clerk Organizations feature provides a way to easily add multi-tenancy into your application.

In this article, you learned how Organizations can be used to allow users to add and modify data across available organizations. By enabling Organizations and slightly tweaking the code based on the token claims, your applications can take advantage of isolated, collaborative environments just like the demo app that was built onto in this guide.

If you enjoyed this article, share it on X and let us know what you liked about it by tagging @clerk!