Skip to main content
Organizations represent your team or business in Braintrust. Each organization contains projects, users, and organization-wide settings. You can create multiple organizations to organize projects differently, and users can be members of multiple organizations. Configure your organization by navigating to Settings > Organization. You can also customize organization settings using the API.

​
Invite members

Add users to your organization:
  1. Navigate to Settings > Organization > Members.
  2. Click Invite.
  3. Enter email addresses (one per line for multiple invites).
  4. Select a permission group (Owners, Engineers, or Viewers).
  5. Click Send invites.
Invited users receive an email with a link to join your organization. They must be assigned to at least one permission group.

​
Configure permission groups

Permission groups are the core of Braintrust’s access control system. They are collections of users that can be granted specific permissions to projects, experiments, and datasets.
  1. Navigate to Settings > Organization > Permission groups.
  2. View existing groups or create new ones.
  3. Assign users to groups when inviting members.
For detailed information about creating and managing permission groups, see Control access.

​
Manage API keys

Create API keys for authentication:
  1. Navigate to Settings > Organization > API keys.
  2. Click Create API key.
  3. Enter a name to identify the key.
  4. Click Create.
  5. Copy the key immediately (it won’t be shown again).
API keys inherit permissions from the user who created them. Organization owners can view and manage all API keys in the organization.
Store API keys securely. Anyone with an API key can access Braintrust with the permissions of the key’s creator.

​
Create service tokens

Service tokens enable system integrations without tying credentials to individual users:
  1. Navigate to Settings > Organization > Service tokens.
  2. Click Create service account.
  3. Enter a name for the service account.
  4. Assign permission groups or grant specific permissions.
  5. Click Create.
  6. Generate a service token for the account.
  7. Copy the token immediately (it won’t be shown again).
Service tokens use the bt-st- prefix. Use them anywhere API keys (sk- prefix) are accepted.
Only organization owners can manage service accounts and service tokens.

​
Configure AI providers

Set up API keys for AI providers used across your organization:
  1. Navigate to Settings > Organization > AI providers.
  2. Click the provider you want to configure.
  3. Enter your API key for that provider.
  4. Click Save.
Configured providers are available in playgrounds, experiments, and the AI Proxy without users needing individual API keys.

​
Add custom providers

Add custom models or endpoints:
  1. Click + Custom provider.
  2. Enter provider details:
    • Name: Display name for the provider.
    • Model name: Identifier used in code (e.g., gpt-3.5-acme).
    • Endpoint URL: API endpoint for the model.
    • Headers: Optional headers (supports Mustache templates with {{email}} and {{model}}).
    • Flavor: Chat or completion.
    • Format: OpenAI, Anthropic, Google, Window, or JS.
    • Streaming: Whether the endpoint supports streaming.
    • Multimodal: Whether the model accepts images.
    • Costs: Input and output token pricing.
  3. Click Save.
Custom providers appear alongside standard providers in model selection dropdowns.

​
Set environment variables

Define secrets available to all functions in your organization:
  1. Navigate to Settings > Organization > Env variables.
  2. Click Add variable.
  3. Enter a key and value.
  4. Click Save.
Environment variables are accessible from prompts, scorers, and tools. Use them for API keys, database credentials, or configuration values. 
// Access in TypeScript functions
const apiKey = process.env.MY_API_KEY;

​
Configure API URLs (self-hosted)

For self-hosted deployments, set custom API URLs:
  1. Navigate to Settings > Organization > API URL.
  2. Enter your URLs:
    • API URL: Main API endpoint.
    • Proxy URL: AI Proxy endpoint.
    • Realtime URL: Realtime API endpoint.
  3. Click Save.
Test connectivity using the provided test commands.

​
Set git metadata logging

Control which git metadata fields are logged:
  1. Navigate to Settings > Organization > Logging.
  2. Select fields to log:
    • Commit hash.
    • Branch name.
    • Author.
    • Commit message.
    • Repository URL.
  3. Click Save.
Git metadata helps track which code version generated specific logs or experiment results.

​
Delete an organization

Deleting an organization permanently removes all projects, logs, experiments, datasets, and functions. This cannot be undone.
Only organization owners can delete organizations:
  1. Navigate to Settings > Organization.
  2. Scroll to the bottom of the page.
  3. Click Delete organization.
  4. Confirm by typing the organization name.
  5. Click Delete.

​
Next steps