Permissions overview

Permissions in Benchling govern what users, teams, organizations, and apps can view or do with data and configurations across the platform. If a user belongs to multiple groups with different permissions, Benchling applies the most permissive access granted by any group or individual setting.

Access policies define the actions that users can take with defined permission types. There are two types of access policies:

• General access policies determine actions a user can take across the tenant. You can customize general access policies in Registry Settings
• Schema access policies determine how users interact with schema definitions and their objects. Schema access policies are not customizable

Access is controlled through a layered system of multiple types of permissions each corresponding to different modules or components in Benchling. These include:

• Project and folder permissions – govern access to entries, files, and structured data within a project, with optional fine-grained access control within projects
• Registry permissions – determine access to registered entities and overall registry settings
• Schema permissions – control access to Connection, Entity, Fieldset, Result, Run, and Study schema definitions
• Inventory permissions – determine how users interact with containers, plates, and locations
• Molecular Biology permissions – apply to enzyme lists, ladders, and feature libraries used to annotate sequences
• Insights permissions – define what users can do with dashboards and analyses
• Template Collection permissions – control access to create, edit, or view templates, subtemplates, Forms, and Request Templates

The linked articles will take you to the main configuration articles for each topic. This guide outlines each type of permission, how they interact, and how to configure them.

Customize access policies

The default general access policies that Benchling provides are:

• Read - can view, but cannot make changes
• Append - can create data, but cannot edit
• Write - can view, create, and edit
• Admin - can view, create, edit, and manage

For more tailored access control, tenant admins can customize policies for specific data types or workflows. Read access is always granted for every item type in a policy.

1. Click your Avatar icon in the bottom-left corner
2. In Feature Settings, click Access Policies
3. To edit an existing access policy, click the desired policy. To create a new access policy:
   • Click the + button next to the Name field in the table header
   • Name your new access policy
   • Select the existing access policy that you want to clone, then click Save
4. Set individual actions for each listed action (grouped by item type, e.g. Entities, Notebook entries) as:
   • Granted
   • Not granted
   • Granted to author (user can act only on items they authored)
5. Click Save when finished; changes take effect immediately
6. To delete an access policy, hover over the policy you want to delete and click the trash icon that appears

Project and folder permissions

Projects are the foundation of access control for most items in Benchling. Permissions on a project determine who can view, create, and modify its contents. Each project must have an owner, and for many tenants, the owner must be an organization. If the owner is an organization, all admins of that organization will have admin access to the project. Project admins can assign additional collaborators permissions to the project. Each user or team can be granted one of the following levels:

• Read: Can view all project contents but cannot make changes
• Append: Can create items within the project
• Write: Can create, edit, and archive items within the project
• Admin: Can manage collaborators, modify project settings, and archive content

Permissions are cumulative; for example, if a user is added with Read access and also belongs to a team with Write access, they will have Write access. 

Folders inherit permissions from the parent project but can also have more specific permissions added at the folder level. If a user has access to a folder but not the parent project, only the folder displays in the Projects panel of the workspace. 

Folders can never be less permissive than their parent project. If a user has Write access to a project, they will have at least Write access to all subfolders in that project. We recommend applying the least permissive access policies to projects and granting additional access to their contained folders, as needed.

Note: Folder permissions are currently not supported in the warehouse or Insights dashboards.  No user will ever see data they don't have access to, but if they don't have at least Read access at the project level they will not be able to find the objects from folders they have access to in the warehouse or Insights dashboards.  All other features like search, Insights Analyses, and the Projects panel will work as expected.

Enable or disable folder permissions

To enable or disable folder permissions, you must be a Tenant Admin.

1. Open the Tenant Admin Console
2. Click Settings, then click Permission Controls
3. Turn on or turn off folder permissions as appropriate

Note: Folders must have permissions removed before disabling folder permissions tenant-wide. If you have admin access to the relevant folders, Benchling will remove any existing folder permissions as part of turning off folder permissions. If you don’t have admin access to those folders, you’ll get a message indicating which folders need to be updated and no changes will be made.

Permission levels

The table below displays the actions users can perform at the project or folder level with default general access policies.

Set project and folder permissions

1. Click the briefcase icon to open the Projects panel
2. Right-click on the project or folder name and click Manage access. Alternatively, open the desired project or folder, click the gear icon next to the project or folder name, then click Manage access
   
   

3. Add new collaborators in the top search bar by searching for user, email, team, organization, or app. Specify the general access policy that should be granted to the user in the right dropdown, and click Add
4. To update project permissions for existing users, use the dropdowns under Access Policies. To update Folder permissions for existing users, use the top search bar to search for the collaborator, select the general access policy that should be granted in the right dropdown, then click Add
5. To remove user permissions from a project or folder, click the … icon next to the collaborator and click Remove. At the folder level, you can only remove user permissions that were granted at the folder level
6. Click Done if you are setting permissions for a new project or folder or Save if you are updating permissions for an existing project or folder
   
    

Registry permissions

Registry-level permissions control who can view, access, and modify Registry configurations and settings, including Registry collaborators, Entity schemas, Entry schemas, Inventory schemas (Containers, Plates, Boxes, and Locations), Dropdowns, Printers, and Label templates.

Permission levels

The table below displays the actions users can perform at the project or folder level with default general access policies.

Note: other schema types are governed by Organization Admin status; Teams can be granted access to create (but not edit) Run and Result schemas and to create and edit Workflow and Request schemas on the Team Settings page.

Set Registry permissions

You must have Registry admin permissions to update Registry permissions.

1. In Feature Settings, click Registry Settings
2. In [Org] Registry settings, click General
3. Add new collaborators in the top search bar by searching for user, email, team, organization, or app. Specify the general access policy that should be granted to the user in the right dropdown, then click Add
4. To update Registry permissions for existing users, use the dropdowns under Access Policies
5. To remove user permissions, click the … icon next to the collaborator and click Remove
6. Click Save to apply the permissions

Determine Registry schema permission source

Registered entities from each Entity schema can use either registry-level or project-level permissions. To change a schema’s permission source, contact Benchling Support.

1. In Feature Settings, click Registry Settings
2. Open the desired schema
3. Under Access Policies, scroll down to the Registering Entities section to check whether the schema uses Registry or Project permissions

Schema permissions

Schema permissions provide granular control over how users interact with schemas and their objects as defined in the table below. Schema permissions and access policies are designed to align with higher-level Registry and project permissions, not override them.

Permission levels

The table below displays the actions users can perform at the schema level with default  schema access policies. Schema access policies cannot be customized.

*Schema objects might additionally depend on higher-level Registry or project permissions.

Configure default schema permissions

Organization admins can configure default schema configurations, which automatically apply to all newly created schemas in an organization and can be set for Connection, Entity, Fieldset, Result, Run, and Study schemas.

1. In Feature Settings, click Access Policies
2. In the menu, click Schema Access Policies, then click the Settings tab
3. Select the organization from the Organization dropdown menu, then select the schema type from the list that displays below it
4. Search for users, teams, or organizations under Default Options, then click Add
5. In the Schema Access Policy column, select the default schema access policy for each collaborator
6. Click Save

Set individual schema permissions

Schema admins can configure permissions on individual schemas.

1. In Feature Settings, click Registry Settings
2. In the menu, click on the schema type that you want to update, then click the individual Connection, Entity, Entry, Run, Result, or Fieldset schema to update
3. Click the Access Policies tab
4. Add new collaborators in the top search bar by searching for user, team, organization, or app. Specify the general access policy that should be granted to the user in the right dropdown, then click Add
5. To update schema permissions for existing users, use the dropdowns under Access Policies
6. To remove user permissions, click … next to the collaborator and click Remove
7. Click Update Collaborators to apply the permissions

Inventory permissions

Inventory items (containers, boxes, and plates) derive permissions from where they reside:

• If in a project/folder, project permissions apply
• If not in a project, registry permissions apply

Locations cannot be placed in projects and always use registry permissions. To view items in Inventory Locations, users must have at least Read permissions to the Registry.

Molecular Biology permissions

Permissions for Feature libraries, Enzyme lists, and Ladders are controlled separately under Molecular Biology settings, and govern what actions users can take to interact with these objects.

Permission levels

Set Molecular Biology permissions

1. In Molecular Biology settings, click the desired object (Feature libraries, Enzyme lists, or Ladders)
2. Open or create the object
3. Click the gear icon
4. Add new collaborators in the Manage collaborators search bar by searching for user, team, organization, or app. Specify the general access policy that should be granted to the user in the Access policies dropdown
5. To update permissions for existing collaborators, use the dropdowns under Access Policies
6. To remove collaborator permissions, hover over the collaborator you want to remove, then click the trash can icon that appears to the right of the Access Policies column
7. Click Save to apply the permissions

Insights permissions

Insights dashboards and analyses must be linked to a project. Project permissions determine what a user can do within Insights. For more information on the data that is visible to users in Insights dashboards and Analysis, see the linked articles. 

Permission levels

*When a user with default Read permission sets parameter values in Insights dashboards, they are applied for the individual user only. When a user with default Write or Admin permission sets parameter values in Insights dashboards, they are applied for all users.

Insights data permissions

Data within an Insights dashboard can be queried from across multiple projects. When an individual user views a dashboard, the query will only return the subset of data from projects to which they have at least Read access.

By contrast, all data within an Insights Analysis, including those pulled from other projects, will be available to users with access to the Analysis.

Frequently asked questions

Q: Is it possible to make a policy that grants READ access to some item types, but NONE access to other item types?

A: No. READ access is the minimum level of access granted for each action in an access policy.

Q: Can I restrict access to a folder without restricting the entire project?
A: No. Folder permissions are additive; user access at the project level will be the minimum user access for all project subfolders.

Q: Is it possible for an entity with project-based permissions to use permissions from the Registry?
A: Yes, if a registered object is not stored in a project, it will use the permissions from the Registry even if the schema is set to use project permissions. Contact Benchling Support to require registered entities to be stored in a project.

Q: Do schema permissions override Registry or project access?
A: No. Schema permissions supplement higher-level access. All levels must align.

Q: What combinations of permissions are required to register an entity?
A: By default, Create schema permissions are required to create an entity and Write Registry permissions are required to register the entity.

Q: Can you set schema access policies from the API?
A: Yes, schema access policies can be managed through the V3 API using the /benchling/collaboration endpoint. You can bulk update schema access policies through the V3 API. This feature is in beta and is not enabled by default and is subject to change. For more about what it means for features to be in beta, see our article that describes the Benchling release stages.

Q: Can you set all schema policies in bulk from the UI?
A: No, it is not possible to bulk assign schema policies through the UI; each schema must be updated manually or through the V3 API endpoint.

Q: Can you remove authorization from an organization or team admin?
A: Yes. To remove authorization from an organization or team admin, remove the organization or team from the schema permissions.

Q: Can you remove schema access for all users?
A: No, at least one admin must be assigned schema access. The same is true for Registry Settings.

Q: Users have access to a project but get access denied messages when they try to create and register objects, how do I resolve this? 

A: Because registering objects in Benchling technically includes actions on the project, registry, and schema, several things are checked for access simultaneously and if any are missing the user will be blocked.  In this case, the user will need the following permissions granted:

• Project access:
  • Project and Folder > Add other items
  • Entities > Edit other data
• Schema access for the schema they're trying to register:
  • Create schema objects
  • Register schema objects
• Registry access:
  • Register entities

Q: Permissions have been changed on a project, can I tell who used to have permissions? 

A: All changes to projects are audited, so you can always look at the audit log to know what has changed about the access on a project.  You can export the audit log by right clicking the project in the project pane or by opening the settings menu when the project is open and selecting "Export audit log."  If the audit log is particularly long, you can use the CSV version and filter it down to "Project: Updated owner" and "Project: Updated collaborators" events so you will only see changes to access.

Q: Why is a change to permissions is showing up in the audit log as permission removed and added, and sometimes the add is listed first? 

Because of the way permissions are stored in Benchling, when permissions are changed Benchling doesn't update the existing stored permission but instead deletes what was set before and adds the new permission.  These actions are done concurrently, so sometimes the add action will appear in the audit log before the delete action.

Q: The access policy for organization members was changed, so why was the action was audited as "updated owner" 

A: If the organization is the owner of a project, when the access policy for the members of that organization is changed Benchling audits that as a change to the owner even though the actual owner is not changing.  You can see this was the case by reviewing the old and new values which will only differ in the access policy assigned to members of the organization.

Q: All of the admins for a project, schema, or template collection are unavailable but we need to get access, what do we do? 

A: For various reasons, sometimes customers will lose access to something important in their tenant when the only admins on that object are unavailable, such as when they leave the company or go on an extended vacation.  In this case, you'll need to contact Customer Support and they can help you add an additional admin so you can regain access.

Q: Why are users not seeing all of their data in Insights Dashboards? 

A: If users should be seeing more data in their insights dashboards than is actually being returned, it's likely that they do not have access to the project where the data are located.  Insights dashboards do not include data that has been granted via folder permissions only, so that data will be missing.

To fix this, ensure that the users have at least Read access at the project level to all data that you want to surface in an insights dashboard.  Alternatively, for some scenarios it might make sense to use insights analysis instead, which will reflect all of the data the user has access to.

Q: Why are users not seeing all of their data in warehouse queries? 

A: If users should be seeing more data in their warehouse queries than is actually being returned, it's likely either a timing issue or that they do not have access to the project where the data are located.  There can be a delay between changes in Benchling and when those changes appear in Warehouse, so the first thing to do is wait a day and see if the problem resolves.

Otherwise, Warehouse queries do not include data that has been granted via folder permissions only, so that data will always be missing.  To fix this, ensure that the users have at least Read access at the project level to all data that you want to surface in warehouse queries.  Alternatively, if you can use APIs to pull the data you need, that will always reflect all of the data the user has access to.