Create custom project roles

Custom project roles allow you to create roles with specific permissions tailored to your team's needs. Unlike the built-in project roles (Admin, Editor, Viewer), custom roles let you define granular access to workflows, credentials, and other project resources.

Create a custom role

Instance owners and instance admins can create custom roles.

To create a custom role:

1. Go to Settings > Roles > Project roles.
2. Select Create role.
3. Enter a role name and optional description.
4. Select the permissions (scopes) for this role:

• Workflow permissions: View, execute, edit, create, publish, transfer, delete, or manage data redaction for workflows
• Credential permissions: View, edit, create, share, unshare, transfer, or delete credentials
• Project permissions: View, edit, or delete projects
• Folder permissions: View, edit, create, transfer, or delete folders
• Execution permission: Reveal redacted execution data
• Secret vault permissions: View, create, edit, delete, or sync secret vaults of a project
• Secrets permission: Use secrets in credentials
• Data table permissions: View tables, view rows, edit tables, edit rows, create, or delete tables
• Project variable permissions: View, edit, create, or delete project variables
• Source control: Push to source control

1. Select Create role.

Assign a custom role to users

Project admins can assign custom roles to project members. Custom roles apply only within the specific project where they're assigned. A user can have different roles in different projects.

To assign a custom role:

1. Select the project.
2. Select Project settings.
3. Under Project members, browse or search for users.
4. Select the user and choose the custom role from the dropdown.
5. Select Save.

Edit a custom role

To update an existing custom role:

1. Go to Settings > Roles > Project roles.
2. Find the custom role you want to edit.
3. Select the three-dot menu > Edit.
4. Update the role name, description, or permissions.
5. Select Save changes.

Duplicate a custom role

To create a new role based on an existing one:

1. Go to Settings > Roles > Project roles.
2. Find the role you want to duplicate.
3. Select the three-dot menu > Duplicate.
4. Update the role name and permissions as needed.
5. Select Create role.

Delete a custom role

To delete a custom role:

1. Go to Settings > Roles > Project roles.
2. Find the role you want to delete.
3. Select the three-dot menu > Delete.
4. Confirm the deletion.

Permission scopes reference

Custom roles use permission scopes to define what users can do within a project. Each scope below matches a checkbox in the Project roles editor. The section headings match the editor's section names; the scope codes are what you'll see in API responses and audit logs.

Workflow scopes

• workflow:create - Create new workflows
• workflow:read - View workflow details
• workflow:update - Edit workflows
• workflow:execute - Execute workflows
• workflow:publish - Publish workflows (also grants workflow:unpublish)
• workflow:delete - Delete workflows
• workflow:move - Transfer workflows between projects
• workflow:enableRedaction - Turn on data redaction for a workflow (refer to Execution data redaction)
• workflow:disableRedaction - Turn off data redaction for a workflow (refer to Execution data redaction)

Credential scopes

• credential:create - Create new credentials
• credential:read - View credential details
• credential:update - Edit credentials
• credential:delete - Delete credentials
• credential:move - Transfer credentials between projects
• credential:share - Share credentials with other users
• credential:unshare - Remove credential sharing

Project scopes

• project:read - View project details
• project:update - Edit project settings
• project:delete - Delete projects

Folder scopes

• folder:create - Create new folders
• folder:read - View folder contents
• folder:update - Rename folders
• folder:delete - Delete folders
• folder:move - Transfer folders

Execution scopes

• execution:reveal - Reveal redacted execution data (refer to Execution data redaction)

Secret vault scopes

The scope codes use the externalSecretsProvider prefix. The role editor lists this section as Secrets vaults.

• externalSecretsProvider:create - Create new secret vaults in a project
• externalSecretsProvider:read - View secret vaults in a project
• externalSecretsProvider:update - Edit secret vault configuration
• externalSecretsProvider:delete - Delete secret vaults from a project
• externalSecretsProvider:sync - Reload a vault's secrets

Secrets scope

The scope code uses the externalSecret prefix. The role editor lists this section as Secrets.

• externalSecret:list - Use secrets in credentials

Data table scopes

• dataTable:create - Create new data tables
• dataTable:read - View data table schema
• dataTable:update - Edit data table schema
• dataTable:delete - Delete data tables
• dataTable:readRow - Read rows from data tables
• dataTable:writeRow - Insert or update rows in data tables

Project variable scopes

• projectVariable:create - Create new variables
• projectVariable:read - View variable values
• projectVariable:update - Edit variable values
• projectVariable:delete - Delete variables

Source control scopes

• sourceControl:push - Push changes to source control

Common custom role examples

These are example custom project roles you can create for common use cases. Remember that these roles apply within individual projects, not across your entire n8n instance.

Workflow developer

A role for users who work only with workflows:

• workflow:create, workflow:read, workflow:update, workflow:execute, workflow:delete
• credential:read (view credentials but not edit them)
• project:read

Credential manager

A role for users who manage credentials:

• credential:create, credential:read, credential:update, credential:delete, credential:share
• workflow:read (view workflows to understand credential usage)
• project:read

Secrets user

A role for users who use external secrets in credentials but don't manage vaults:

• externalSecret:list (use secrets in credential expressions)
• credential:create, credential:read, credential:update (manage credentials with secrets)
• workflow:read
• project:read

Workflow publisher

A role for users who can publish workflows without full edit access:

• workflow:read, workflow:publish
• credential:read
• project:read