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

# Manage permissions

> Create permission groups, assign permissions, and provision service accounts

Set up permission groups, assign members, set organization and project permissions, and provision service accounts for system integrations. For the permission model, see the [Access control overview](https://docs.braintrust.dev/admin/access-control.md).

## Create custom permission groups

Build groups with specific permissions:

> [!NOTE]
>
> Custom permission groups are only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Under **Permission groups**, click **Create permission group**.
3. Enter a name and description.
4. Set the group's permissions. Select organization-level permissions in the **Organization**, **All projects**, and **AI providers** columns. To add project-specific and object-level permissions, click  **Add project** under **Projects** or  **Add project group** under **Project groups**.
5. Click **Create**.

## Edit or delete a permission group

Edit a permission group's name, description, permissions, and members in one sheet:

> [!NOTE]
>
> Editing a permission group's name, description, and permissions is only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Click the group's row, or click the edit icon () on its row.
3. Edit the **Name** or **Description (optional)**. You can change a built-in group's description but not its name.
4. To change what the group grants, select the **Permissions** tab. See [Set organization permissions](#set-organization-permissions). To add or remove members, select the **Members** tab. See [Manage group membership](#manage-group-membership).
5. Click **Save**. Saving applies every change in the sheet at once, including changes to the name, description, permissions, and members.

If you close the sheet with unsaved changes, Braintrust asks whether to **Keep editing** or **Discard changes**.

To copy the group's ID for use with the [groups API](https://docs.braintrust.dev/api-reference/groups/list-groups.md), click the ID next to the group's name at the top of the sheet.

To rename a group or edit its description, you need both **Update** on the group and **Manage access** on the organization. Without **Manage access** on the organization, the sheet shows only the **Members** tab.

To delete a custom permission group, click **Delete** in its sheet, or click the delete icon () on its row, then confirm. Deleting a group requires **Delete** on the group. Built-in permission groups can't be deleted.

> [!WARNING]
>
> Deleting a permission group can't be undone. Its members lose any access granted through the group. Access they have from other permission groups or direct permissions is unaffected.

## Manage access to a permission group

Control who can administer a permission group itself: who can view it, edit its permissions, rename it, or grant others access to it. This is separate from the permissions the group grants its members. For the distinction, see [Permissions vs. Manage access](https://docs.braintrust.dev/admin/access-control.md#permissions-vs-manage-access).

> [!NOTE]
>
> Manage access is only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Hover over the group's row, then click the manage access icon ().
3. In the dialog that opens, select the tab for who you want to grant access to: **Permission groups**, **Members**, or **Service accounts**.
4. Search for the user, group, or service account, then click the edit icon next to it.
5. Select the permissions to grant on the group:
   * **Read**: View the group and its permissions.
   * **Update**: Edit the group's name, description, and permissions.
   * **Delete**: Delete the group.
   * **Manage access**: Grant and revoke access to the group (super-user ability).
6. Click **Save**.

## Set organization permissions

Grant organization-level permissions to custom groups:

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Click the group's row, or click the edit icon () on its row, then select the **Permissions** tab.
3. Select organization-level permissions:
   * **Manage settings**: Change organization configuration.
   * **Invite members**: Invite users.
   * **Remove members**: Remove users (organizations must have at least one member).
   * **Manage access**: Grant and revoke permissions (super-user ability).
   * **View account billing**: View the [billing account](https://docs.braintrust.dev/admin/billing.md#view-account-billing) shared with other linked organizations. Appears only for organizations linked to an account.
   * **Read audit logs**: Read organization audit log entries.
4. Select permissions for all projects:
   * **Read**: View all projects and their resources.
   * **Create**: Create projects, and create experiments, logs, and datasets in all projects.
   * **Update**: Modify existing resources in all projects.
   * **Delete**: Remove resources from all projects.
   * **Manage access**: Grant permissions on all projects.
5. (Optional) To set project-specific and object-level permissions, click  **Add project** under **Projects**, select a project, choose its permissions, then click **Continue**.

   This lets you set project-specific and object-level permissions directly from the permission group, without opening the **Project** tab of each project's **Permissions** settings.
6. Click **Save**.

> [!WARNING]
>
> **Manage access** is a super-user permission. Users with this permission can grant themselves any other permission. Assign it carefully.
>
> **Manage settings** grants users the ability to change organization-level settings, like the API URL.

## Set project permissions

Specify a group's permissions for a particular project and its objects:

1. [Create a custom permission group](#create-custom-permission-groups).
2. In your project, go to ** Settings** > ** Permissions** > [**Project**](https://www.braintrust.dev/app/~/configuration/permissions/project).
3. Search for your group.
4. Click the pencil icon next to the group.
5. Select project permissions:
   * **Read**: View project and its resources.
   * **Create**: Create experiments, logs, datasets.
   * **Update**: Modify existing resources.
   * **Delete**: Remove resources.
   * **Manage access**: Grant permissions on this project.
6. Select object-level permissions for experiments, datasets, logs, prompts, playgrounds, functions, scorers, and classifiers:
   * **Create**: Create the object.
   * **Read**: View the object.
   * **Update**: Modify the object.
   * **Delete**: Remove the object.
   * **Manage access**: Grant permissions on this object.
7. Click **Save**.

Users must have Read permission on a project to see it in the UI.

## Manage project groups

A project group is a named collection of projects. Grant a permission group access to the project group once, and every project in the group inherits that access. Without project groups, giving a team the same access across 100 projects means creating and maintaining 100 separate project-level grants. For how project-group access works, see [How permissions work](https://docs.braintrust.dev/admin/access-control.md#how-permissions-work).

> [!NOTE]
>
> Project groups are only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

Use a project group when the same team, role, or service account needs the same access across multiple projects.

Creating a project group requires the **Create** permission in the **All projects** column. To create a project group:

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Under **Project groups**, click **Create project group**.
3. Enter a **Name** and an optional **Description**.
4. In the **Projects** section, select the projects to include. A project can belong to more than one project group.
5. Click **Create project group**.

Then grant access to the project group from a permission group. See [Set project group permissions](#set-project-group-permissions).

> [!TIP]
>
> Grant access to permission groups rather than to individual members whenever you can. Group-based ownership is easier to audit, and access stays correct as people join and leave teams. Use members for one-off exceptions, and service accounts for automations and integrations.

To change a group's name, description, or projects, click its row in the project groups list, or click the edit icon () on the row. Make your changes, then click **Save**. Membership is edited in this sheet, not from the **Projects** column in the list.

Editing a group requires **Update** on its **Project group definition** row. Adding or removing a project also requires **Manage access** on that project, so you can only change membership for projects you administer. Removing a project from a group revokes only the access that group granted. Permissions the project has from other sources stay in effect.

> [!NOTE]
>
> A project group can contain up to 10,000 projects. The limit applies only when you add projects, so a save that only removes projects succeeds even when a group is over the limit. A single save can change up to 1,000 project assignments, counting additions and removals together. To assign more projects than that, save in batches.

To remove a group, click the delete icon () on its row.

> [!WARNING]
>
> Deleting a project group requires **Delete** on its **Project group definition** row and **Manage access** on every project in the group. Deletion removes the permissions its member projects inherited from the group. The projects themselves are not deleted. Deleting a group frees its name for reuse.

## Set project group permissions

Grant a permission group access to every project in a project group. A project group's permissions have two parts:

* **Member projects**: Controls access to the projects in the group, together with the object-level rows.
* **Project group definition**: Controls the group itself and doesn't grant access to its projects. **Update** lets the holder rename the group, edit its description, change its projects, and create new projects in it. **Delete** lets the holder delete the group.

To give a member or service account project-group access directly, edit their [direct permissions](#set-direct-permissions):

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Click the group's row, or click the edit icon () on its row, then select the **Permissions** tab.
3. Under **Project groups**, click  **Add project group**.
4. Select a project group, then set its permissions. On the **Member projects** row:
   * **Read**: View the projects in the group and their resources.
   * **Create**: Create experiments, logs, and datasets in those projects.
   * **Update**: Modify existing resources in those projects.
   * **Delete**: Remove resources from those projects.
   * **Manage access**: Grant permissions on those projects.
5. (Optional) To let the permission group manage the project group itself, set permissions on the **Project group definition** row.
6. (Optional) Set object-level permissions for experiments, datasets, logs, prompts, playgrounds, functions, scorers, and classifiers. These work the same as they do at the project level, and apply to those objects in every project in the group. See [Set project permissions](#set-project-permissions).
7. Click **Continue**, then click **Save**.

### Project group owners

A permission group, member, or service account with every permission on every row of the project group's permissions is an Owner of that project group. The rows are **Project group definition**, **Member projects**, **Experiments**, **Datasets**, **Logs**, **Prompts**, and **Playgrounds**. The permissions can come from direct grants or a role, on the project group or inherited from the organization. For example, every permission in the **All projects** column makes a permission group an Owner of every project group in the organization. The creator of a project group gets every permission on the **Project group definition** row, so they also need the other rows to be an Owner. Project-group Owners can create service accounts and service tokens without being organization owners. See [Use service accounts](#use-service-accounts).

## Manage group membership

Users can belong to multiple permission groups, either directly or through a group that is itself a member of another group. Their effective permissions are the union of all group permissions.

To change the groups a specific user belongs to:

1. Go to ** Settings** > [** Members**](https://www.braintrust.dev/app/~/configuration/members).
2. Find the member, then click  **Manage permissions** on their row.
3. Select **Edit permission groups**.
4. The dialog lists the groups you can manage under **Member of**, **Member of via inheritance** (groups the user joins through another group's membership), and **Not a member of**.
5. To add: Click **+** next to a group under **Not a member of**.
6. To remove: Click the **x** next to a group under **Member of**.

The **Members** column in the permission groups list shows each group's member count. Hover over the count to see member names.

To view and edit all members of a specific group:

1. Go to ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
2. Click the group's row, or click the edit icon () on its row, then select the **Members** tab.
3. To add: Search for a user, then click **+** next to their name under **Non-members**.
4. To remove: Click the **x** next to a user under **Group members**.
5. Click **Save**. Membership changes apply only when you save.

Users under **Members with inherited membership** belong to this group through another group they're in. You can't remove them here. To remove one, remove them from every group that gives them this membership.

> [!NOTE]
>
> Both paths are disabled for permission groups managed by [SCIM provisioning](https://docs.braintrust.dev/admin/scim.md). To change membership, edit the mapped group in your identity provider instead. Groups without a SCIM mapping are unaffected.

## Set direct permissions

A direct permission is granted to one member or service account instead of through a permission group, so changing a permission group's permissions or membership doesn't affect it. To find where a member's access to a project comes from, see [Inheritance labels on the project permissions page](https://docs.braintrust.dev/admin/access-control.md#inheritance-labels-on-the-project-permissions-page). To set a service account's direct permissions, see [Use service accounts](#use-service-accounts).

> [!NOTE]
>
> Editing a member's direct permissions is only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

To set a member's direct permissions:

1. Go to ** Settings** > [** Members**](https://www.braintrust.dev/app/~/configuration/members).
2. Find the member, then click  **Manage permissions** on their row.
3. Select **Edit direct permissions**.
4. Select the permissions to grant or remove. The dialog has the same columns and **Projects** and **Project groups** sections as a permission group's **Permissions** tab. See [Set organization permissions](#set-organization-permissions). Permissions the member inherits from a permission group are shown but can't be edited here.
5. Click **Save**.

## Use service accounts

A service account is an identity for system integrations, authenticated with a service token that you use like an API key. Unlike a personal API key, which inherits the full permissions of the user who created it, a service account is a separate identity whose permissions come from its own permission group memberships and isn't tied to any individual.

Service tokens also support [user impersonation](https://docs.braintrust.dev/api-reference.md#impersonate-users). The service account must have the `Owner` role in every organization the target user belongs to, and the target user must belong to at least one organization. Braintrust checks the service account's permissions, not those of the token's creator.

Use service accounts to:

* **Authenticate integrations and [automations](https://docs.braintrust.dev/admin/data-management/export.md)** that shouldn't depend on one person's account. A service account keeps working even after team members leave.
* **Grant least-privilege, project-scoped access.** Because its permissions come from its own groups, you can scope a service account more restrictively than your own access, for example to a single project or a subset of projects. A personal API key can't be scoped below your own permissions.
* **Separate environments.** Create distinct tokens for development, staging, and production, each assigned to a permission group scoped to the right projects.

To create a service account:

1. Go to ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/service-tokens).
2. Click **+ Service token**.
3. Enter a service account name.
4. Assign permission groups or grant specific permissions. To scope the account to specific projects, assign it to a permission group limited to those projects.
5. Click **Create**.
6. Copy and save the auto-generated service token somewhere safe and accessible. For security reasons, you will not be able to view it again. If you lose the service token, you must create a new one.
7. Use the token like an API key in SDK or API calls.

Organization owners can manage all service accounts in the organization. Owners of an active project group can manage a service account when it has a permission grant on that project group, including a grant inherited through a permission group. Only organization owners can assign service accounts to permission groups. Adding or removing direct permissions requires permission to manage ACLs on the target object. To create a service token, you must have all of the service account's permissions in the organization. Existing tokens immediately inherit later permission changes. To edit its permission groups:

1. Go to ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/service-tokens).
2. Find the service account, then click the more options menu () on its card.
3. Select **Edit permission groups**.
4. The dialog lists the groups you can manage under **Member of**, **Member of via inheritance**, and **Not a member of**.
5. To add: Click **+** next to a group under **Not a member of**.
6. To remove: Click the **x** next to a group under **Member of**.

To set its direct permissions:

1. Go to ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/service-tokens).
2. Find the service account, then click the more options menu () on its card.
3. Select **Edit direct permissions**.
4. Select the permissions to grant or remove. Permissions the service account inherits from its permission groups are shown but can't be edited here. To change them, update the service account's group membership instead.
5. Click **Save**.

Project-group Owners who aren't organization owners see **Edit permissions in** followed by the project group's name on the card instead. It sets the service account's permissions on that project group.

> [!NOTE]
>
> Organization owners and [Owners of an active project group](#project-group-owners) in the organization can create service tokens, at \*\* Settings\*\* > [\*\* Service tokens\*\*](https://www.braintrust.dev/app/~/configuration/service-tokens) in the Braintrust UI or by calling [`POST /v1/service_token`](https://docs.braintrust.dev/api-reference/servicetokens/create-service-token) with a service token whose account has organization-owner permissions or owns an active project group in the organization. Project-group Owners can list or revoke tokens for an account with a permission grant on a project group they own. Creating a token requires all of the account's permissions in the organization. If you are missing any permissions, the request returns a 403 error. Existing tokens continue to use the account's permissions after permission changes. User API keys cannot be used to create service tokens. If the calling service token has an expiration, the new token's `expires_in_seconds` must be set and can't exceed the caller's remaining lifetime. Otherwise, the request returns a 403 error that states the maximum allowed value.
>
> Organization owners and Owners of an active project group in the organization can create service accounts by calling [`PATCH /v1/organization/members`](https://docs.braintrust.dev/api-reference/organizations/modify-organization-membership). Project-group Owners must provide `invite_users.project_group_id` for a group they own and cannot assign permission groups. Providing `invite_users.project_group_id` grants the account read access to that project group. Additional direct permissions can be granted through the existing permissions controls. To also create an initial service token, include `token_name` (this requires authenticating with a service token whose account has organization-owner permissions or owns an active project group in the organization). If that service token has an expiration, the same limit applies to `token_expires_in_seconds`. If the initial token is rejected, the request fails and no service accounts are created.

> [!NOTE]
>
> For self-hosted deployments, you must configure a service token for the data plane to enable features like data retention. See [Data plane manager](https://docs.braintrust.dev/admin/self-hosting/configure/telemetry.md#data-retention) for more details.

## Programmatic access control

To automate the creation of permission groups and their access control rules, use the Braintrust API. See the API reference for [groups](https://docs.braintrust.dev/api-reference/groups/list-groups.md) and [permissions](https://docs.braintrust.dev/api-reference/acls/list-acls.md).

For a project group, set an ACL's `object_type` to match the permissions you're granting:

* `project_group`: Permissions on the group itself, like the **Project group definition** row.
* `project_group_projects`: Access to the group's projects, like the **Member projects** and object-level rows.

To manage permission groups, project groups, and their access control rules as code, use the [Braintrust Terraform provider](https://docs.braintrust.dev/reference/terraform.md).

## Next steps

* Review the [permissions reference](https://docs.braintrust.dev/admin/access-control.md#permissions-reference) to understand what each permission grants.
* [Set up automations](https://docs.braintrust.dev/admin/data-management/export.md) with service accounts.
* [API reference](https://docs.braintrust.dev/api-reference/groups/list-groups.md) for programmatic access control.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.