> ## Documentation Index > Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Access control > Control who can access your projects, experiments, and data using permission groups scoped to the organization, project, and object levels ## How permissions work Braintrust uses a hierarchical permission model built around *permission groups*, which are collections of users (or [service accounts](/admin/access-control/manage-permissions#use-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**](https://www.braintrust.dev/app/~/configuration/org/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](/plans-and-limits#plans): | Capability | Starter | Pro | Enterprise | | ---------------------------------------------------------------------------- | :-----: | :-: | :--------: | | **Owners** built-in group | ✓ | ✓ | ✓ | | **Engineers** and **Viewers** built-in groups | — | ✓ | ✓ | | Custom permission groups | — | — | ✓ | | Project-level permissions | — | — | ✓ | | Object-level permissions (experiments, datasets, logs, prompts, playgrounds) | — | — | ✓ | 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. | 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**](https://www.braintrust.dev/app/~/configuration/org/team) or add them to the group's member list from ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/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. For setup instructions, see [Create custom permission groups](/admin/access-control/manage-permissions#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). | 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](#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. | ### Organization-only permissions These permissions exist only at the organization level and control administrative actions on the organization itself: | Permission | What it allows | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | **Manage settings** | Change organization-level configuration, including the API URL and billing. | | **Manage members** | Invite new users to the organization. | | **Remove members** | Remove users from the organization. (At least one member must remain.) | | **Read audit logs** | Read audit log entries for the organization, such as permission changes, member invites, and API key creation. | ### 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) * Project tags * Span iframes * MCP servers * Project automations, including retention policies **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 * [Manage permissions](/admin/access-control/manage-permissions) to create permission groups, set organization and project permissions, and provision service accounts. * [Manage organizations](/admin/organizations) to invite members and assign groups. * [Manage projects](/admin/projects) to configure project-level permissions.