Skip to main content
Braintrust provides flexible access control at organization, project, and object levels. Use permission groups to grant users specific permissions across resources.

​
Built-in permission groups

Every organization starts with three permission groups:
  • Owners: Full access to organization, data, and settings. Can invite/remove members, manage permissions, and delete resources
  • Engineers: Can create, read, update, and delete projects and resources. Cannot manage members or access controls
  • Viewers: Read-only access to projects and resources. Cannot create, update, or delete anything
These groups are scoped to the entire organization. Assign users to built-in groups when inviting them or from the Members page.

​
Create custom permission groups

Build groups with specific permissions:
  1. Navigate to Settings > Permission groups.
  2. Click Create permission group.
  3. Enter group name and description.
  4. Click Create.
After creating a group, configure its permissions.

​
Set organization permissions

Grant organization-level permissions to custom groups:
  1. Find the group in the permission groups list.
  2. Click Permissions.
  3. Select permissions to grant:
    • Read organization: View organization details.
    • Create projects: Start new projects.
    • Manage members: Invite and remove users.
    • Manage settings: Change organization configuration.
    • Manage access: Grant and revoke permissions (super-user ability).
    • Create API keys: Generate authentication credentials.
  4. 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

Limit group access to specific projects:
  1. Create a custom permission group.
  2. Navigate to the project’s Configuration page.
  3. Click Permissions in the context menu.
  4. Search for your group in the search input.
  5. Click the pencil icon next to the group.
  6. 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.
  7. Click Save.
Users must have Read permission on a project to see it in the UI.

​
Set object permissions

Grant access to specific experiments, datasets, or prompts:
  1. Create a custom permission group.
  2. Grant the group Read permission on the parent project.
  3. Navigate to the specific object (experiment, dataset, or prompt).
  4. Click Permissions from the context menu.
  5. Search for your group.
  6. Click the pencil icon.
  7. Select object-level permissions:
    • Read: View the object.
    • Update: Modify the object.
    • Delete: Remove the object.
    • Manage access: Grant permissions on this object.
  8. Click Save.
Object permissions inherit from project permissions but can be further restricted.

​
Manage group membership

Add or remove users from permission groups:
  1. Navigate to Settings > Permission groups.
  2. Click on a group name.
  3. Click Members.
  4. To add: Search for users and click Add.
  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.

​
Set group access permissions

Control who can view and manage permission groups themselves:
  1. Navigate to Settings > Permission groups.
  2. Click on a group name.
  3. Click Group access.
  4. Configure permissions:
    • Read group: View group details and members.
    • Update group: Modify group name and description.
    • Delete group: Remove the group.
    • Manage members: Add and remove group members.
  5. Click Save.

​
Use service accounts

Service accounts provide credentials for system integrations:
  1. Navigate to Settings > Service tokens.
  2. Click Create service account.
  3. Enter service account name.
  4. Assign permission groups or grant specific permissions.
  5. Click Create.
  6. Click Generate token for the service account.
  7. Copy the token (starts with bt-st-).
  8. 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 and manage service accounts.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.

​
Common access patterns

​
Restrict project access

Create a project-specific group:
  1. Create a permission group named after the project.
  2. Do NOT grant organization-level permissions.
  3. Grant Read, Create, Update on the specific project.
  4. Add relevant users to the group.

​
Create read-only analysts

Allow data analysis without modification:
  1. Create a “Data Analysts” group.
  2. Grant organization-level Read permission.
  3. Grant project-level Read permission on relevant projects.
  4. Exclude Create, Update, Delete permissions.

​
Set up contractors

Limit external access to specific resources:
  1. Create a “Contractors” group.
  2. Grant project-level Read permission only.
  3. Grant object-level Read permission on specific experiments or datasets.
  4. Review and remove access when contracts end.

​
Programmatic access control

Automate permission management with the API: 
// Create a permission group
const response = await fetch("https://api.braintrust.dev/v1/group", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${BRAINTRUST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Data Scientists",
    description: "Team with experiment access",
    org_name: "My Organization",
  }),
});

const group = await response.json();
For more information on using the API to manage permission groups, see the API reference for groups and permissions.

​
Next steps