> ## 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 organizations

> Configure organization settings and integrations

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 going to <Icon icon="settings-2" /> **Settings**. You can also customize organization settings using the [API](/api-reference).

## Create an organization

To create a new organization:

1. Click your organization name in the upper-left corner and select **+ Create organization**.

2. Enter a name for your organization.

3. Select a **[data plane region](#data-plane-region)** (US or EU) from the dropdown. The region is pre-selected based on your location, but you can change it before continuing.

   <Warning>
     After creating an organization, you cannot change its data plane region.
   </Warning>

4. Click **Continue**.

After creating an organization, you'll see onboarding information you can follow to instrument your code and start logging traces to Braintrust.

### Data plane region

Braintrust's architecture has two main components:

* The **data plane** stores all sensitive data, including experiment records, logs, traces, spans, datasets, and prompt completions. It consists of the Braintrust API, a PostgreSQL database, Redis cache, object storage, and Brainstore (a high-performance query engine for real-time trace ingestion).

* The **control plane** provides the web UI, authentication, user management, and metadata storage (project names, experiment names, organization settings). The control plane does not store or process your sensitive data.

<Accordion title="Breakdown of where data is stored">
  | Data                                                                          | Location                    |
  | ----------------------------------------------------------------------------- | --------------------------- |
  | Experiment records (input, output, expected, scores, metadata, traces, spans) | Data plane                  |
  | Log records (input, output, expected, scores, metadata, traces, spans)        | Data plane                  |
  | Dataset records (input, output, metadata)                                     | Data plane                  |
  | Prompt playground prompts                                                     | Data plane                  |
  | Prompt playground completions                                                 | Data plane                  |
  | Human review scores                                                           | Data plane                  |
  | Project-level LLM provider secrets (encrypted)                                | Data plane                  |
  | Org-level LLM provider secrets (encrypted)                                    | Control plane               |
  | API keys (hashed)                                                             | Control plane               |
  | Experiment and dataset names                                                  | Control plane               |
  | Project names                                                                 | Control plane               |
  | Project settings                                                              | Control plane               |
  | Git metadata about experiments                                                | Control plane               |
  | Organization info (name, settings)                                            | Control plane               |
  | Login info (name, email, avatar URL)                                          | Control plane               |
  | Auth credentials                                                              | [Clerk](https://clerk.com/) |
</Accordion>

Each data plane region has its own endpoint:

| Region | API URL                         | MCP endpoint                        |
| ------ | ------------------------------- | ----------------------------------- |
| US     | `https://api.braintrust.dev`    | `https://api.braintrust.dev/mcp`    |
| EU     | `https://api-eu.braintrust.dev` | `https://api-eu.braintrust.dev/mcp` |

<Note>
  `https://gateway.braintrust.dev` is the global hosted gateway endpoint. It uses DNS latency routing and health checks across Braintrust-hosted gateway regions. Gateway routing is separate from your organization's [data plane region](/admin/organizations#data-plane-region). When [logging is enabled](/deploy/gateway#enable-logging), gateway logs are written to your organization's configured data plane.
</Note>

After creating an organization, you can view its data plane region and API URL at **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url).

<Tip>
  If your organization requires storing data in your own cloud, see [Deployment options](/admin/deployment) to compare BYOC and self-hosting.
</Tip>

## Manage members

### Invite members

To add members to your organization:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="users-round" /> Members**](https://www.braintrust.dev/app/~/configuration/org/team).
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**.

You can also invite members directly from the [projects page](/admin/projects#view-projects) by selecting the <Icon icon="users-round" /> **Members** > <Icon icon="mail" /> **Invite members**.

Invited members receive an email with a link to join your organization. They must be assigned to at least one permission group.

### Remove members

To remove members from your organization:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="users-round" /> Members**](https://www.braintrust.dev/app/~/configuration/org/team).
2. Find the member you want to remove.
3. Click the <Icon icon="trash-2" /> icon next to their name.

<Note>
  Organizations must have at least one member. You cannot remove yourself from an organization. To transfer ownership or leave an organization, ensure another member is present and can manage the organization after you leave.
</Note>

## 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. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="shield-check" /> Permission groups**](https://www.braintrust.dev/app/~/configuration/org/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](/admin/access-control).

## Manage API keys

Create API keys for authentication:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys).
2. Click **+ 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.

<Note>
  API keys can be created only in the Braintrust UI, not through the API.
</Note>

<Note>
  Store API keys securely. Anyone with an API key can access Braintrust with the permissions of the key's creator.
</Note>

## Create service tokens

Service tokens enable system integrations without tying credentials to individual users:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="server" /> Service tokens**](https://www.braintrust.dev/app/~/configuration/org/service-tokens).
2. Click **+ Service token**.
3. Enter a name for the service account.
4. Assign permission groups or grant specific permissions.
5. Enter a name for the service token.
6. Click **Create**.
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.

<Note>
  Only organization owners can create service tokens, either at **<Icon icon="settings-2" /> Settings** > [**<Icon icon="server" /> 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) and authenticating with a service token that has organization-owner permissions. User API keys cannot be used to create service tokens.
</Note>

## Configure AI providers

Configure organization-wide AI provider credentials so playgrounds, experiments, and the gateway can call models without users needing individual API keys. See [Configure AI providers](/admin/ai-providers).

## Select models for Loop

[Loop](/loop) requires organization-level AI providers to function. Before selecting models, ensure you have [configured AI providers](/admin/ai-providers) at the organization level.

Select which models your organization can use in Loop:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="blend" /> Loop**](https://www.braintrust.dev/app/~/configuration/org/loop).
2. Select models.

## Enable Slack integration

Connect Slack to send alerts and notifications to your channels:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="toy-brick" /> Integrations**](https://www.braintrust.dev/app/~/configuration/org/integrations).
2. Click **Enable Slack**.
3. Authorize Braintrust to access your Slack workspace.
4. Select which channels Braintrust can access.

Once enabled, you can configure alerts to send notifications to specific Slack channels. See [Set up alerts](/admin/automations/alerts) and [Set up spend alerts](/admin/billing/monitor-usage#set-up-spend-alerts) for details.

If the Braintrust Slack app is updated with new permissions, a warning banner and **Refresh permissions** button will appear next to your connected workspace. Click **Refresh permissions** to re-authorize through the OAuth flow and enable the latest features.

## Set environment variables

Define secrets available to all functions in your organization:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="chevrons-left-right" /> Env variables**](https://www.braintrust.dev/app/~/configuration/org/env-vars).
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. Each variable lists a redacted preview of its value and a **Last updated** timestamp that tracks when the value itself was last changed, along with the user who made the change. Renaming a variable or editing other metadata does not bump this timestamp.

<CodeGroup dropdown>
  ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  // Access in TypeScript functions
  const apiKey = process.env.MY_API_KEY;
  ```

  ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  # Access in Python functions
  import os
  api_key = os.environ["MY_API_KEY"]
  ```
</CodeGroup>

## Configure API URLs (self-hosted)

For [self-hosted deployments](/admin/self-hosting), set custom API URLs:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url).

2. Enter your URLs:
   * **API URL**: Main API endpoint.
   * **Gateway URL**: Gateway endpoint.
   * **Realtime URL**: Realtime API endpoint.

3. If your data plane is deployed behind a VPN or on a private network (not accessible from the public internet), enable **Data plane is on a private network**.

   This checkbox enables detection of Chrome Local Network Access permission issues. When enabled, if fetch requests fail due to blocked LNA permissions, Braintrust will display instructions on how to grant the necessary permissions in Chrome settings.

4. Click **Save**.

Test connectivity using the provided test commands.

When you configure these API URLs, Braintrust automatically provisions a service token for your data plane. This enables features like [data retention](/admin/automations/configure-data-retention) without requiring manual service token setup. You can view and manage this token in the [Service tokens](#create-service-tokens) section.

<Note>
  Braintrust-hosted organizations (US or EU) can view their region and API URL by navigating to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url).
</Note>

## Set git metadata logging

Control which git metadata fields are logged:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="scroll-text" /> Logging**](https://www.braintrust.dev/app/~/configuration/org/logging).
2. Enable **Collect git metadata**.
3. Select the fields to log. Your changes save automatically.

Git metadata helps track which code version generated specific logs or experiment results.

<Note>
  Diff content is opt-in. By default, Braintrust collects standard git metadata but not the **Diff** field. To capture diffs, enable **Diff** here. The server strips `git_diff` from logged repo info unless your org has enabled it, regardless of what the SDK sends (data plane v2.2.0 or later).

  Until you save a policy here, the Python SDK (v0.23.0+) collects no git metadata by default. Pass `git_metadata_settings` in code to override.
</Note>

## Control image rendering

External images in logs can send sensitive data to untrusted servers when your browser loads them. Configure image rendering to control this risk:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="scroll-text" /> Logging**](https://www.braintrust.dev/app/~/configuration/org/logging).
2. Under **Security**, select an **Image rendering** mode:
   * **Auto-load images**: Images are loaded automatically (default).
   * **Click to load**: Show placeholder, click to load each image.
   * **Block all images**: Never load external images.

## Configure environments

Create environments to version prompts and functions:

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="layers" /> Environments**](https://www.braintrust.dev/app/~/configuration/org/environments).
2. Click **+ Environment**.
3. Enter environment name (e.g., "production", "staging", "dev").
4. Click **Create environment**.

Assign prompt and function versions to environments to separate development from production. See [Manage environments](/deploy/environments) for details.

## Monitor infrastructure (self-hosted)

Organization owners and admins can view infrastructure metrics for self-hosted deployments directly from the Braintrust UI. See [Monitor your infrastructure](/admin/self-hosting#monitoring) for details.

## Delete an organization

To delete an organization, [contact Braintrust](https://braintrust.dev/contact).

## Next steps

* [Control access](/admin/access-control) with permission groups
* [Manage projects](/admin/projects) within your organization
* [Use the Braintrust gateway](/deploy/gateway) for centralized provider access
* [Set up automations](/admin/automations) for alerts and data management