Define custom roles
Enterprise plans
Enterprise add-on
Use custom roles to create customized user permissions and workflows.
If you'd like to add this feature on to your Enterprise plan, contact your Account Executive, email sales@builder.io, or reach out to us through our contact form.
Prerequisites
To define custom roles, make sure:
- You're familiar with Builder's standard roles and permissions.
- You have this feature as an add-on.
Types of permissions and access
You can define new custom roles that have any or all of the permissions and access below. Permissions are broken down by product below.
Builder Content permissions
| Permission | Description |
Publish/Unpublish content | User can publish or unpublish content entries. This permission also controls scheduling. |
Reprioritize content | User can set content priority from the Content List. |
Edit designs | User can edit styles from the Style tab. This permission also controls the resize buttons, preview tools, and the AI assistant. |
Edit folders | User can edit or remove folders in the Asset Library, Symbol Gallery, Template Gallery, and Content Listing. Content folders are available only when the content folders feature is enabled. |
Manage advanced settings | User can open the space-wide Advanced Settings, including proxy previews. This permission is always on for Admin and off for View Only. For older roles, it follows the Edit code permission. |
View Only | User can view but not change anything. When you select this permission, all other checkboxes are locked and Admin is turned off. Users with this permission can't manage advanced settings. |
Create content | User can add new content entries. |
Edit layouts | User can add, remove, and rearrange blocks in the Visual Editor. When this setting is off, users can only edit options such as text and images. The built-in Editor role can't edit spacing, even when this setting is on. |
Edit code | User can add and edit code within Builder, such as custom HTML, CSS, and JS. This permission also controls custom queries, code views, saving views, and locale settings. For older roles, it also determines access to Advanced Settings. |
Edit AI instructions | User can edit the space's AI instructions. This permission is on by default for custom roles and off for View Only. |
Admin | User can manage all users and billing. This permission also grants all other permissions. |
Access
User can access all models or only the models the Admin selects. To allow all models, select the All models checkbox.
You can adjust permissions at the Space level or for each content model. This means you can limit a custom role to certain models. Within each model, you can apply filters for more granular control. Filters use the fields, data, and targeting properties of the model.
For example, you might use the same model across multiple projects in the same space. The projects might be domains, locales, or environments. To let certain users access only specific projects that use that model, create a custom role with model-specific permissions and filters.
Locale access
User can edit all locales or only the locales the Admin selects. Select Edit all locales to allow all locales. Select Allow editing for selected locale(s) to choose specific locales.
Environment permissions
These permissions appear only when the Environments feature is enabled and you're working in a space that is itself an environment.
- Allow linking: User can link or unlink the content and models of a child environment from the main environment.
- Push content/models: User can push content or models from one environment to another. You can also limit which environments the role can push to, including main.
Builder Code permissions
Builder Code permissions control what users can do with projects and their connected code repositories:
| Permission | Description |
Edit code directly | The user can both view and edit project files directly in the Code editor, instead of only prompting the AI. |
Merge pull requests | User can merge pull requests from within Builder. This permission is off by default. |
Modify workflow integrations | User can connect, configure, and disconnect the Slack and Jira integrations and the Review agent. This permission also requires a paid plan. The Review agent requires a Team or Enterprise plan. |
Publish sites with Builder | User can publish and unpublish Builder-hosted websites. This permission appears only when Builder hosting is enabled for the space. |
Create projects | User can create new projects from scratch or from a repository. This permission also controls duplicating projects. It is on by default for custom roles. |
Admin | User can manage all users and billing. This permission also grants all other permissions. |
Send pull requests | User can create pull requests from changes to the project's connected repository. This permission is on by default for custom roles. |
Modify MCP servers | User can add, update, and remove custom connectors. These are Model Context Protocol servers. Builder calls them connectors in the interface. |
Modify project settings | User can change project configuration such as environment variables, build settings, and runtime options. |
Connect code repository | User can link an external Git repository to create or update a project. Turning on this permission also turns on Create projects. |
Index design systems | User can index design systems. |
View Only | User can view but not change anything. When you select this permission, all other checkboxes are locked and Admin is turned off. Users with this permission can't manage advanced settings. |
Access
Use Project Access Level to choose whether the role applies to All projects or only Some projects.
Override Builder Code permissions per project
When you set a role's access to Some projects, you can set these permissions for each project:
- Edit code directly
- Send pull requests
- Merge pull requests
- Modify project settings
- Publish sites with Builder
- Create branches. This is allowed by default.
The other Builder Code permissions apply to the whole space.
Built-in role defaults for Builder Code
Builder's built-in roles start with these Builder Code permissions:
- Developer and Admin have all Builder Code permissions.
- Designer has Create projects and Publish sites with Builder.
- Editor, Contributor, and View only don't have Create projects.
Shared and similar permissions
Some permissions appear in both tables or have similar names:
- Edit code in Builder Content and Edit code directly in Builder Code are the same setting. A role with it turned on has both. In Builder Content, it covers custom HTML, CSS, and JS in the Visual Editor. In Builder Code, it covers editing project files in the Code editor.
- Admin and View Only are shared. They appear in both tables and apply to both Builder Content and Builder Code.
- Publish/Unpublish content and Publish sites with Builder are different permissions. The first applies to content entries. The second applies to Builder-hosted websites.
- Create content and Create projects are different permissions.
- The other Builder Code permissions have no Builder Content equivalent.
Set permissions
- Go to your Space Settings.
- Click the Pencil icon to the right of Roles.
- Click + New Role.
- Give the new role a Name and Description.
- Choose the Permissions you'd like. The tables above describe each one.
- Click Save.
Grant permissions on a per-model basis
When choosing permissions as above, you can specify particular models.
- Follow steps 1-5 above.
- Select All Models if you'd like this role's permissions to apply to all models.
- Deselect All Models to display a list of the available models. Choose the models you'd like to apply the permissions to.
Refine model permissions with filters
- To further refine permissions when selecting individual models, expand that model and click + Filter.
- Select the model's property to add permissions for that property.
- Click Save.
The following video demonstrates these steps.
You can select any locale that you have configured. You can also select the Default locale. This is the locale you specified as your default.
Try out roles with the role switcher
As an Admin, you can confirm that an assigned role gives users the intended access. This works for custom roles and built-in roles. To experience Builder as a given role, use the role switcher. For details, visit Verifying role access with the role switcher in Managing Users.
What's next
To learn more, see Builder Code roles & permissions, Builder Content roles & permissions, and Manage users.