Skip to main content

​
How permissions work

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).

​
Rules to consider

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.

​
Plan-specific access control features

The level of access control available depends on your plan:
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.

​
Built-in permission groups

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. 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.

​
When to use custom permission groups

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.
Project-level read is often all you need to share resources across projects. For example, granting read access to a central scorer project makes its scorers available in dropdowns across the organization, without organization-wide read access. See Use scorers from another project. For setup instructions, see Create custom permission groups.

​
Permissions reference

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.

​
Object permissions

These permissions apply to organizations, projects, and individual objects within projects (experiments, datasets, logs, prompts, playgrounds).

​
Organization-only permissions

These permissions exist only at the organization level and control administrative actions on the organization itself:

​
What Update covers

The Update permission controls modifications to existing resources. At the project scope, it includes: Project-level resources:
  • Project name and description
  • Project scores (human review scores; not automated evaluation scores). Per-score visibility is a soft filter, not an access boundary. See Restrict score visibility.
  • Project tags
  • Span iframes
  • MCP servers
  • Project automations, including retention policies
  • Project-level AI provider credentials. See Configure AI providers.
Resources inside the project:
  • Experiment metadata and event data
  • Dataset metadata and records
  • Logs
Update does not include Create, Delete, or Manage access — each is granted separately.

​
Permissions vs. Manage access

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.

​
Next steps