Skip to main content
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.

​
Create custom permission groups

Build groups with specific permissions:
only available on the Enterprise plan.
  1. Go to Settings > Permission 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.
only available on the Enterprise plan.
  1. Go to Settings > Permission 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.
  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).
  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.
  2. In your project, go to Settings > Project 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.
  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

Service accounts provide credentials for system integrations:
  1. Go to Settings > Service tokens.
  2. Click + Service token.
  3. Enter service account name.
  4. Assign permission groups or grant specific permissions.
  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.
Service accounts are not tied to individual users. They maintain access even when team members leave.
Only organization owners can create service tokens, at Settings > Service tokens in the Braintrust UI or by calling POST /v1/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. To also create an initial service token, include token_name (this requires authenticating with a service token that has organization-owner permissions).
For hybrid deployments, you must configure a service token for the data plane to enable features like data retention. See Data plane manager 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 and permissions.

​
Next steps