> ## 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.
# Manage permissions
> Create permission groups, assign permissions, and provision service accounts
export const feature_2 = "Project groups"
export const verb_2 = "are"
export const feature_1 = "Manage access"
export const verb_1 = "is"
export const feature_0 = "Custom permission groups"
export const verb_0 = "are"
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](/docs/admin/access-control).
## Create custom permission groups
Build groups with specific permissions:
{feature_0} {verb_0} only available on the [Enterprise plan](/docs/plans-and-limits#plans).
1. Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).
2. Click **Create permission group**.
3. Enter a name and description.
4. Set the group's permissions inline. Configure organization-level permissions for the **Organization** and **All projects** columns, plus project-specific and object-level permissions in the **Project-specific permissions** section.
5. Click **Create**.
## 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](/docs/admin/access-control#permissions-vs-manage-access).
{feature_1} {verb_1} only available on the [Enterprise plan](/docs/plans-and-limits#plans).
1. Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).
2. Find the group in the permission groups list, then click the more options menu () on its row.
3. Select ** Manage access**.
4. In the **Object permissions** dialog, select the tab for who you want to grant access to: **Permission groups**, **Members**, or **Service accounts**.
5. Search for the user, group, or service account, then click the edit icon next to it.
6. 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).
7. Click **Save**.
## Set organization permissions
Grant organization-level permissions to custom groups:
1. Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).
2. Find the group in the permission groups list, then click **Permissions** on its row.
3. Select organization-level permissions:
* **Manage settings**: Change organization configuration.
* **Manage members**: Invite users.
* **Remove members**: Remove users (organizations must have at least one member).
* **Manage access**: Grant and revoke permissions (super-user ability).
* **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) Select project-specific and object-level permissions in the **Project-specific permissions** section.
This section lets you set project-specific and object-level permissions directly from the permission group dialog, without going to each project's **Project permissions** settings.
6. Click **Save**.
**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** > [** Project permissions**](https://www.braintrust.dev/app/~/configuration/permissions).
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](/docs/admin/access-control#how-permissions-work).
{feature_2} {verb_2} only available on the [Enterprise plan](/docs/plans-and-limits#plans).
Use a project group when the same team, role, or service account needs the same access across multiple projects.
You create a group, grant access to it, and choose its projects in a single sheet:
1. Go to ** Settings** > [** Project groups**](https://www.braintrust.dev/app/~/configuration/org/project-groups).
2. Click **Create project group**.
3. Enter a **Name** and an optional **Description**.
4. In the **Permissions** section, choose which permission groups, members, and service accounts can access the group. Select the **Permission groups**, **Members**, or **Service accounts** tab, click the edit icon () next to a group, member, or service account, select the permissions to grant, then click **Apply**.
You can also grant access later from the permission group itself. See [Set project group permissions](#set-project-group-permissions).
5. In the **Projects** section, select the projects to include. A project can belong to more than one project group.
6. Click **Create project group**.
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, permissions, 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.
Adding or removing a project 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.
A project group can contain up to 10,000 projects. 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.
You need **Manage access** on every project in a group to delete it. Deleting a project group 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 a project group from the permission group side. To grant the same access while creating the project group, use the **Permissions** section described in [Manage project groups](#manage-project-groups).
1. Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).
2. Find the group in the permission groups list, then click **Permissions** on its row.
3. In the **Project and project-group permissions** section, find **Project groups** and click **Project group**.
4. Select a project group, then set its permissions:
* **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) 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).
6. Click **Save**.
## 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/org/team).
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**.
To view and edit all members of a specific group:
1. Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).
2. Find the group in the permission groups list.
3. Click **Members**.
4. To add: Search for users and click **+**.
5. To remove: Click the **x** next to a user's name.
## 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.
Use service accounts to:
* **Authenticate integrations and [automations](/docs/admin/data-management/export)** 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/org/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.
Only [organization owners](/docs/admin/access-control#built-in-permission-groups) can edit a service account's permission groups after creation:
1. Go to ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/org/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**.
The service account's **Edit direct permissions** dialog shows the project permissions it inherits from its permission groups, labeled "Inherited from \[group name]". Inherited permissions can't be edited there. To change them, update the service account's group membership instead.
Only organization owners can create service tokens, at ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/org/service-tokens) in the Braintrust UI or by calling [`POST /v1/service_token`](/docs/api-reference/servicetokens/create-service_token) with a service token that has organization-owner permissions. User API keys cannot be used to create service tokens.
Users with permission to add organization members can create service accounts by calling [`PATCH /v1/organization/members`](/docs/api-reference/organizations/modify-organization-membership). To also create an initial service token, include `token_name` (this requires authenticating with a service token that has organization-owner permissions).
For self-hosted deployments, you must configure a service token for the data plane to enable features like data retention. See [Data plane manager](/docs/admin/self-hosting/configure/telemetry#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](/docs/api-reference/groups/list-groups) and [permissions](/docs/api-reference/acls/list-acls).
## Next steps
* Review the [permissions reference](/docs/admin/access-control#permissions-reference) to understand what each permission grants.
* [Set up automations](/docs/admin/data-management/export) with service accounts.
* [API reference](/docs/api-reference/groups/list-groups) for programmatic access control.