> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/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 organizations, project groups, projects, and objects ## How permissions work Braintrust uses a hierarchical permission model built around *permission groups*, which are collections of users (or [service accounts](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#use-service-accounts)) that share a set of permissions. Permissions cascade down the following 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 group**: A named collection of projects. Permissions granted on the group's member projects apply to every project in the group and the objects inside those projects. Permissions on the group definition let holders manage the group itself, but don't grant access to its projects. * **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. Project groups follow the same rule, so they cannot narrow access a project already has. * **Group permissions are unioned.** A user can belong to multiple groups. Their effective permissions are the union of every group they're in. A project can belong to multiple project groups, and its permissions are the union of every project group it's in. * **Project group membership takes effect immediately.** Braintrust resolves a project's group memberships when it checks a permission, rather than copying permissions onto the project. Adding a project to a group, or removing it, changes effective access right away. * **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** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization). When an organization owner turns off this toggle, they also have the option to remove all *existing* direct owner grants. ### Inheritance labels on the project permissions page On a project's ** Settings** > ** Permissions** > [**Project**](https://www.braintrust.dev/app/~/configuration/permissions/project) tab, each entry with access on the **Permission groups**, **Members**, and **Service accounts** tabs shows **Direct access** or **Inherited access**. An **Inherited access** label lists the sources of that access in parentheses, for example **Inherited access (Engineers, Organization Project)**. When more than three permission groups contribute, the label shows the first three and the number of others. Each source is one of two kinds. **Organization**, **Organization Project**, and **Project group** say where a grant was made. A permission group name says which permission group the access comes through. | Source | What it means | | - | - | | **Organization** | A grant on the organization itself, from membership in **Owners** or from the **Organization** column of a permission group's, member's, or service account's permissions. Not every grant with this label reaches the project. **Owners** membership grants full access to the project, and **Manage access** lets the holder manage the project's permissions. Other **Organization** permissions, such as **Manage settings**, also show this label but don't grant access to the project's data. | | **Organization Project** | A grant from the **All projects** column. It covers every project in the organization, including projects created later. | | **Project group** | A grant on the member projects of a [project group](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#manage-project-groups) that contains this project. The grant goes to a permission group, member, or service account, and applies to every project in the project group. Grants on the **Project group definition** row don't reach the project. | | A permission group name, such as **Engineers** | Access comes through that permission group. The member or service account belongs to it, either directly or through another permission group. See [Manage group membership](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#manage-group-membership). | | **Organization**, **Organization Project**, or **Project group** with no permission group name | On the **Members** and **Service accounts** tabs, access is granted directly to that member or service account, not through a permission group. On the **Permission groups** tab, access is granted to the permission group itself. | Permission group names and the other sources are listed separately, so the label doesn't say which permission group holds which grant. For example, **Inherited access (Engineers, Organization Project)** can mean that the Engineers permission group has an **All projects** grant, that the member has their own **All projects** grant and also gets access through Engineers, or both. To tell them apart, check the member's [direct permissions](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#set-direct-permissions). Because permissions are additive, project-level settings cannot remove inherited access. To change who can reach a project, change the grant where it comes from: * **A permission group's grant:** [Edit the permission group's permissions](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#set-organization-permissions). To remove only one member's access, [remove them from the permission group](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#manage-group-membership). * **A member's direct grant:** [Edit the member's direct permissions](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#set-direct-permissions). * **A service account's direct grant:** [Edit the service account's direct permissions](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#use-service-accounts). ### Plan-specific access control features The level of access control available depends on your [plan](https://docs.braintrust.dev/plans-and-limits.md#plans): | Capability | Starter | Pro | Enterprise | | - | :-: | :-: | :-: | | **Owners** built-in group | ✓ | ✓ | ✓ | | **Engineers**, **Viewers**, and **All AI Provider Access** (When organization AI provider permissions launched, Braintrust added every organization’s existing members and service accounts to this group, including organizations on the Starter plan. New members are not added automatically.) built-in groups | — | ✓ | ✓ | | Custom permission groups | — | — | ✓ | | Project groups | — | — | ✓ | | Project-level permissions | — | — | ✓ | | Object-level permissions (AI providers, experiments, datasets, logs, prompts, playgrounds) | — | — | ✓ | > [!NOTE] > > 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 | | **All AI Provider Access** | Read access to every organization AI provider, and no other permissions. See [Organization AI providers](https://docs.braintrust.dev/admin/ai-providers.md#organization-ai-providers). | Pro and Enterprise (When organization AI provider permissions launched, Braintrust added every organization’s existing members and service accounts to this group, including organizations on the Starter plan. New members are not added automatically.) | To assign a user to a built-in group, invite them from ** Settings** > [** Members**](https://www.braintrust.dev/app/~/configuration/members), add them to the group's member list from ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization), or use that member's **Manage permissions** menu on the Members page. See [Manage group membership](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#manage-group-membership) for details. > [!NOTE] > > 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 organization AI providers or objects within a project (experiments, datasets, logs, prompts, or playgrounds). * Assemble a permission set that doesn't match Owners, Engineers, Viewers, or All AI Provider Access (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](https://docs.braintrust.dev/evaluate/score-online.md#use-scorers-from-another-project). For setup instructions, see [Create custom permission groups](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#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, organization AI providers, and individual objects within projects (experiments, datasets, logs, prompts, and 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 export via the API and SDK. No separate export-only permission exists. In the UI, download and export controls are shown only to users who also have `Update` or `Delete`. | | **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. | | **Invite 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. | | **View account billing** | View the [billing account](https://docs.braintrust.dev/admin/billing.md#view-account-billing) shared by organizations that Braintrust links under one contract. Appears only for organizations linked to an account. | ### 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](https://docs.braintrust.dev/annotate/human-review.md#restrict-score-visibility). * Project tags * Span iframes * MCP servers * Project automations, including retention policies * Project-level AI provider credentials. See [Configure AI providers](https://docs.braintrust.dev/admin/ai-providers.md#permissions-and-access). **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 edit a group's **Permissions** tab, 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](https://docs.braintrust.dev/admin/access-control/manage-permissions.md) to create permission groups, set organization and project permissions, and provision service accounts. * [Manage organizations](https://docs.braintrust.dev/admin/organizations.md) to invite members and assign groups. * [Manage projects](https://docs.braintrust.dev/admin/projects.md) to configure project-level permissions. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.