User Management and Access Permissions

Hello and welcome back!

In our previous lessons, we built a robust foundation for our self-hosted n8n instance. We've configured persistent storage using Docker volumes, set up a reverse proxy for secure access, and connected n8n to a powerful PostgreSQL database. Your setup is now architecturally sound, but it's still a single-user environment.

Today, we'll address the final piece of the self-hosting puzzle: collaboration and access control. The learning outcome for this lesson is to enable user management and configure basic access permissions. This will transform your personal n8n instance into a secure, multi-tenant platform ready for team projects, which is a key step toward your goal of building complex integrations for teams and products.

1. Enabling User Management: Creating the Owner Account

By default, a self-hosted n8n instance runs in a single-user mode. To enable a multi-user environment, you must first create an owner account. This account has the highest level of privileges and is responsible for managing the entire instance.

The process involves two main stages: optionally configuring an email server for invitations and then performing the in-app setup.

Step 1: (Optional but Recommended) Configure SMTP

n8n uses an SMTP (Simple Mail Transfer Protocol) server to send emails for user invitations and password resets. For a production environment, this is highly recommended.

However, to keep our focus on user management itself, we'll leverage a helpful feature: n8n allows you to skip SMTP setup and instead manually copy and share invitation links with new users. The only trade-off is that users won't be able to use a "forgot password" feature.

For future reference, when you are ready to set up SMTP, you'll need to add several environment variables to your .env file.

Step 2: Create the Owner Account

This is the crucial step. The first time you start a fresh n8n instance (one without any existing user data), it will present you with a signup screen to create the owner account.

If you have been following along, your instance already has data. To trigger this setup, you would need to:

1. Stop your n8n Docker container (docker compose down).
2. Temporarily rename the volume directory for your PostgreSQL data (e.g., from postgres_data to postgres_data_backup). This forces PostgreSQL to initialize a fresh, empty database.
3. Start the instance again (docker compose up -d).

Once you do this, navigating to your n8n URL will show the owner account creation screen.

After creating your owner account, you can stop the instance again, restore your original database volume, and restart. Your owner account will now be registered with your existing data.

2. The Hierarchy of Permissions: Instance vs. Project Roles

With an owner account in place, you can now invite other users. n8n employs a two-tiered permission system that provides granular control, which is essential for managing a team with different responsibilities.

1. Instance-Level Roles: These define a user's capabilities across the entire n8n instance.
2. Project-Level Roles (RBAC): These define what a user can do within a specific project.

This diagram provides a high-level overview of the account types and their general access domains.

Let's break down the roles at each level.

Instance-Level Roles

• Owner: The super-administrator. There is only one. This account is created during the initial setup and has irrevocable permissions to manage the instance, including billing, instance settings, and all users.
• Admin: An administrator can manage users and their permissions, but cannot perform certain owner-level actions like changing the instance license or deleting the owner. You can promote other users to the Admin role.
• User (or Member): A standard user account. By default, users can create projects and have full control over them. Their access to other projects is determined by the project-level roles they are assigned.

Project-Level Roles (Role-Based Access Control - RBAC)

Within any given project, a user can be assigned one of three roles. This is where you can implement the principle of least privilege. For example, a user can be an Admin in one project and a Viewer in another.

To summarize the project roles:

• Project Admin: Has full control over the project. Can manage settings, add/remove members, change member roles, and has full CRUD (Create, Read, Update, Delete) access to all workflows and credentials within that project.
• Project Editor: Can view, create, update, and delete workflows and credentials within the project, but cannot manage project settings or members.
• Project Viewer: A read-only role. Can view workflows, credentials, and executions, but cannot make any changes or even execute workflows manually.

3. Putting It All Together: Inviting and Managing Users

Now let's walk through the practical application. As the instance Owner, you can start building your team.

1. Invite a New User:

   • Log in with your owner account.
   • Click the user icon/menu in the bottom-left corner and go to Settings.
   • Navigate to the Users section.
   • Click Invite and enter the new user's email.
   • If you configured SMTP, they will receive an email. If not, n8n will provide you with a unique registration link to share with them manually.

2. Manage Instance-Level Roles:

   • On the same Users page, you can see a list of all users.
   • You can click on a user to change their instance-level role (e.g., promote a User to Admin).

3. Manage Project-Level Roles:

   • From the main n8n dashboard, you can create a new Project.
   • Open the project, click the "Members" or "Share" button.
   • Here, you can add users from your instance to this specific project.
   • For each user you add, you can assign them the appropriate role: Project Admin, Editor, or Viewer.

Test your understanding!

You are setting up n8n for your company. You need to provide access to three people:

1. Alice: A senior developer who will co-manage the entire n8n instance with you, including adding new users.
2. Bob: A junior developer who needs to create and edit workflows in a project called "Marketing Automations". He should not be able to modify the project settings or manage other users.
3. Charlie: A business analyst who needs to review workflow logic and check past executions for reporting purposes in the "Marketing Automations" project, but must not be allowed to make any changes.

What instance-level and project-level roles would you assign to Alice, Bob, and Charlie?

Show answer

1. Alice:

   • Instance-level Role: Admin. This gives her the ability to manage users and other instance-wide settings.
   • Project-level Role: She would likely be a Project Admin on most projects, giving her full control.

2. Bob:

   • Instance-level Role: User.
   • Project-level Role (for "Marketing Automations"): Project Editor. This allows him to work on workflows and credentials without being able to change project settings or member access.

3. Charlie:

   • Instance-level Role: User.
   • Project-level Role (for "Marketing Automations"): Project Viewer. This gives him the read-only access he needs for his analysis without any risk of accidental changes.

Conclusion

Congratulations! You have now completed the final and most critical module on self-hosting n8n. By enabling user management, you have transformed your instance from a personal tool into a secure, collaborative platform ready for production use.

Key Takeaways:

• User management is enabled by creating a single Owner account for the instance, a process triggered on a fresh database.
• SMTP configuration is recommended for professional user onboarding but can be bypassed by manually sharing invitation links.
• n8n uses a two-tiered permission model: instance-level roles (Owner, Admin, User) for global management and project-level roles (Project Admin, Editor, Viewer) for granular access control within projects.
• This layered security approach allows you to effectively and safely manage teams with diverse responsibilities.

Preview of the Next Lesson:

With your self-hosted n8n instance fully configured and secured, our focus now shifts from setup to operations. In the next lesson, we will begin the "Production Operations and Scaling" module by learning how to monitor workflow execution history and logs for production issues. This is the first step in maintaining a healthy and reliable automation platform.