> ## 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_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](/admin/access-control).
## Create custom permission groups
Build groups with specific permissions:
{feature_0} {verb_0} only available on the [Enterprise plan](/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](/admin/access-control#permissions-vs-manage-access).
{feature_1} {verb_1} only available on the [Enterprise plan](/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 experiments, logs, 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 group membership
Add or remove users from permission groups:
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.
Users can belong to multiple permission groups. Their effective permissions are the union of all group permissions.
## 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](/admin/automations)** 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 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`](/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`](/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](/admin/self-hosting/advanced#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](/api-reference/groups/list-groups) and [permissions](/api-reference/acls/list-acls).
## Next steps
* Review the [permissions reference](/admin/access-control#permissions-reference) to understand what each permission grants.
* [Set up automations](/admin/automations) with service accounts.
* [API reference](/api-reference/groups/list-groups) for programmatic access control.