Braintrust uses a hierarchical permission model built around permission groups, which are collections of users (or service accounts) that share a set of permissions. Permissions cascade down the following three-level hierarchy:
Organization: The top level. Permissions granted at the organization level apply to every project and every object within those projects, including projects created later.
Project: Permissions granted at the project level apply to a single project and the objects inside it.
Object: The most granular level. Permissions granted at the object level apply to that specific object (for example, experiment, dataset, log, prompt, or playground).
Braintrust permissions are subject to the following rules:
Permissions are additive only. Permissions granted at a higher scope cannot be removed at a lower scope. If a user has organization-level Read permissions, you cannot use project-level groups to restrict their access to specific projects. Instead, remove them from the broader group and grant project-level access.
Group permissions are unioned. A user can belong to multiple groups. Their effective permissions are the union of every group they’re in.
The same model applies to service accounts. Service accounts can be members of permission groups, just like users. The hierarchy and cascade rules apply identically.
Creators get a direct owner grant by default. When a user creates an object, they receive owner access to that object directly, in addition to any inherited organization and project permissions.Organization owners can turn this off for newly created objects with the Create direct ownership grants toggle at the top of Settings > Permission groups. When an organization owner turns off this toggle, they also have the option to remove all existing direct owner grants.
To grant permissions at the project or object level, use custom permission groups (Enterprise only). Built-in permission groups (all plans) apply to the entire organization.
Braintrust provides built-in permission groups for managing team access. These groups are scoped to the entire organization. Permissions granted through a built-in group cascade to all projects in the organization, including projects created later.
Group
Access
Plan availability
Owners
Full access to organization, projects, data, and settings. Can invite/remove members, manage permissions, and delete resources.
All plans
Engineers
Create, read, update, and delete projects and resources across the organization. Cannot manage members, access controls, or organization settings.
Pro and Enterprise
Viewers
Read-only access to all projects and resources across the organization. Cannot create, update, or delete anything.
Pro and Enterprise
To assign a user to a built-in group, invite them from Settings > Members or add them to the group’s member list from Settings > Permission groups.
Built-in groups are groups with default names and permissions. An Owner can add permissions to a built-in group but cannot remove any default permissions.
Use custom permission groups (Enterprise) when you need to:
Grant access to a subset of projects rather than the entire organization.
Restrict access to specific objects (experiments, datasets, logs, prompts, or playgrounds) within a project.
Assemble a permission set that doesn’t match Owners, Engineers, or Viewers — for example, a group that can read data across all projects but only update prompts in one.
Each permission applies to a scope (organization, project, or object) or controls administrative actions at the organization or group level. When granted at the organization level, scope-based permissions cascade to all projects and the objects within them.
These permissions apply to organizations, projects, and individual objects within projects (experiments, datasets, logs, prompts, playgrounds).
Permission
What it allows
Read
View the object and its contents. At the project level, lets users see the project and its data. Includes data download and export capabilities. No separate export-only permission exists, so any user with Read can export.
Create
Create new resources within the scope. At the project level, includes creating experiments, datasets, logs, prompts, and playgrounds.
Update
Modify existing resources within the scope. For the full list, see What Update covers.
Delete
Remove resources. Granted independently of Update; having Update does not let you delete.
Manage access
Grant and revoke permissions on this object. A super-user permission: a user with Manage access on a scope can grant themselves any other permission on that scope. Assign carefully.
Permissions and Manage access control different things:
Permissions define what group members can do across all projects (organization-level) or within a single project (project-level). When you click Permissions on a group, you are setting what that group’s members can do in Braintrust.
Manage access defines who can administer the group itself: who can invite new members, rename it, edit its permissions, or grant access to it. When you grant Manage access on a group, you are deciding who controls the group — not what its members can do.
The same distinction applies to projects and objects: Manage access on a project controls who can change the project’s permissions, while the other permissions control what those people can do with the project’s data.
