> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/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 ** Settings**. Its sidebar lists organization, project, and personal settings together under headings such as **Team**, **Automations**, and **Data**, and project settings apply to the project you're working in. To find a setting, type its name in **Search settings** at the top of the sidebar, or search for it in the command bar. You can also customize organization settings using the [API](https://docs.braintrust.dev/api-reference.md).

## Create an organization

To create a new organization:

1. Click your organization name in the breadcrumbs at the top of the page 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.

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] 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/) |

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](https://docs.braintrust.dev/admin/organizations.md#data-plane-region). When [logging is enabled](https://docs.braintrust.dev/deploy/gateway.md#enable-logging), Gateway logs are written to your organization's configured data plane.

After creating an organization, you can view its data plane region and API URL at ** Settings** > [** Data plane**](https://www.braintrust.dev/app/~/configuration/data-plane).

> [!TIP]
>
> If your organization requires storing data in your own cloud, see [Deployment options](https://docs.braintrust.dev/admin/deployment.md) to compare BYOC and self-hosting.

## Find your organization ID

Your organization ID is a UUID used in API calls, [self-hosting configuration](https://docs.braintrust.dev/admin/self-hosting/configure/security.md#configure-organization-authorization), and audit log queries.

To copy your organization ID or name to the clipboard:

1. Click your organization name in the breadcrumbs at the top of the page.
2. Hover over the current organization (marked with a checkmark) to open its submenu.
3. Select **Copy organization ID** or **Copy organization name**.

## Manage members

### Invite members

To add members to your organization:

1. Go to ** Settings** > [** Members**](https://www.braintrust.dev/app/~/configuration/members).
2. Click **Invite**.
3. Enter email addresses (one per line for multiple invites).
4. Select one or more permission groups.
5. Click **Send invites**.

You can also invite members directly from the [projects page](https://docs.braintrust.dev/admin/projects.md#view-projects) by selecting the  **Members** >  **Invite members**.

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

> [!NOTE]
>
> When [SCIM provisioning](https://docs.braintrust.dev/admin/scim.md) manages your organization's membership, **Invite** is disabled and the API rejects membership changes. Add the user to your identity provider's mapped group instead. Service accounts are exempt and can still be added by hand.

### Remove members

To remove members from your organization:

1. Go to ** Settings** > [** Members**](https://www.braintrust.dev/app/~/configuration/members).
2. Find the member you want to remove.
3. Click the  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]
>
> When [SCIM provisioning](https://docs.braintrust.dev/admin/scim.md) manages your organization's membership, the  remove control is disabled and the API rejects membership changes. Remove the user from your identity provider's mapped group instead. Service accounts are exempt and can still be removed by hand.

## 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 ** Settings** > [** Permissions**](https://www.braintrust.dev/app/~/configuration/permissions/organization).
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](https://docs.braintrust.dev/admin/access-control.md).

## Manage API keys

Create API keys for authentication:

1. Go to ** Settings** > [** API keys**](https://www.braintrust.dev/app/~/configuration/api-keys).
2. Click **+ API key**.
3. Enter a name to identify the key.
4. Choose an expiration. It defaults to one year and cannot be changed after creation.
5. Click **Create**.
6. 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.

To list every member's API keys programmatically, call `GET /v1/organization/api_keys` as an [organization owner](https://docs.braintrust.dev/admin/access-control.md#built-in-permission-groups):

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl --request GET \
  --url https://api.braintrust.dev/v1/organization/api_keys \
  --header "Authorization: Bearer $BRAINTRUST_API_KEY"
```

The response contains key metadata only, never the key secret. Service tokens aren't included. To list them, call `GET /v1/service_token`. `GET /v1/api_key` returns only your own keys, even for organization owners.

* The endpoint lists keys in the organization your API key is scoped to. If your key isn't scoped to an organization, pass the `org_id` query parameter.
* Callers who aren't owners of the organization get an empty list, not an error. A request whose `org_id` doesn't match the organization your API key is scoped to also gets an empty list.
* Each request returns up to 1,000 keys. To list more, pass the last key's `id` as the `starting_after` query parameter and repeat until a request returns no keys.

> [!NOTE]
>
> API keys can be created only in the Braintrust UI, not through the API.

> [!NOTE]
>
> Store API keys securely. Anyone with an API key can access Braintrust with the permissions of the key's creator.

### Disable API key creation

To prevent members from creating new API keys:

1. Go to ** Settings** > [** API keys**](https://www.braintrust.dev/app/~/configuration/api-keys).
2. Toggle **Disable API key creation** on.

When API key creation is disabled, members cannot create new keys. Existing keys continue to work. The setting applies only to personal API keys and doesn't block [service token creation](#create-service-tokens). Only [organization owners](https://docs.braintrust.dev/admin/access-control.md#built-in-permission-groups) can change this setting.

## Create service tokens

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

1. Go to ** Settings** > [** Service tokens**](https://www.braintrust.dev/app/~/configuration/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. Choose an expiration. It defaults to one year and cannot be changed after creation.
7. Click **Create**.
8. Copy the token immediately (it won't be shown again).

[Project-group Owners](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#project-group-owners) select a project group when creating the account. The account receives read access to that group. Only organization owners can assign permission groups during creation.

Service tokens use the `bt-st-` prefix. Pass a service token as the bearer token in API requests or as the API key in SDK calls. Requests use the service account's permissions.

Service tokens also support [user impersonation](https://docs.braintrust.dev/api-reference.md#impersonate-users) when the service account has the `Owner` role in every organization the target user belongs to. The target user must belong to at least one organization. These requirements apply to the service account, not the person who created the token.

> [!NOTE]
>
> Organization owners and [Owners of an active project group](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#project-group-owners) in the organization can create service tokens, either at \*\* Settings\*\* > [\*\* Service tokens\*\*](https://www.braintrust.dev/app/~/configuration/service-tokens) in the Braintrust UI or by calling [`POST /v1/service_token`](https://docs.braintrust.dev/api-reference/servicetokens/create-service-token) and authenticating with a service token whose account has organization-owner permissions or owns an active project group in the organization. Project-group Owners can list or revoke tokens for an account with a permission grant on a project group they own. Creating a token requires all of the account's permissions in the organization. If you are missing any permissions, the request returns a 403 error. Existing tokens continue to use the account's permissions after permission changes. User API keys cannot be used to create service tokens. If the calling service token has an expiration, the new token's `expires_in_seconds` must be set and can't exceed the caller's remaining lifetime. Otherwise, the request returns a 403 error that states the maximum allowed value.

## 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](https://docs.braintrust.dev/admin/ai-providers.md).

## Configure Loop

### Choose models for Loop

[Loop](https://docs.braintrust.dev/loop.md) runs on Braintrust's [built-in models](https://docs.braintrust.dev/admin/ai-providers.md#manage-built-in-models) or on your organization's own OpenAI-compatible [AI providers](https://docs.braintrust.dev/admin/ai-providers.md).

### Set a default provider for Loop

Choose the provider that new Loop threads and [automations](https://docs.braintrust.dev/loop/automations.md) use across your organization. Loop selects that provider’s recommended model. Automations with **Auto** on follow this setting on every run, so changing it affects their future runs. Members can choose a different provider or model for individual threads and automations.

> [!NOTE]
>
> On self-hosted deployments where Loop runs in the browser instead of on the [Loop runtime](https://docs.braintrust.dev/admin/self-hosting/configure/loop-runtime.md), the **Loop default provider** setting isn't available.

Only members of the **Owners** [permission group](https://docs.braintrust.dev/admin/access-control.md), or a custom permission group with the **Manage settings** organization permission, can change the default provider.

1. Go to ** Settings** > [** Models**](https://www.braintrust.dev/app/~/configuration/models/organization).
2. Under **Loop default provider**, select **Braintrust**, if built-in models are available, or an organization provider that serves a [supported Loop model](https://docs.braintrust.dev/loop.md#choose-a-provider-and-model). Only organization providers can be the default. To add a provider, select  **Add provider**.

After you set the default:

* **Unavailable default:** If **Loop default provider** shows **Provider unavailable**, choose another provider or resolve the issue shown, such as missing access or no supported Loop models. See [Models and providers](https://docs.braintrust.dev/loop/manage.md#models-and-providers) for how new threads choose a provider in this case.
* **Project overrides:** Inside a project, a [project provider](https://docs.braintrust.dev/admin/ai-providers.md#project-providers) with the same name as the default overrides it. If that provider serves no supported Loop model, the default is unavailable in the project, and Loop doesn't fall back to the organization provider.

### Control Loop logging

By default, Braintrust logs frontend Loop interactions for product improvement and support. To opt out:

1. Go to ** Settings** > [** Models**](https://www.braintrust.dev/app/~/configuration/models/organization).
2. Turn off **Enable logging for Loop**.

When Loop logging is off, Loop continues to work normally, but Braintrust does not log frontend interactions. Self-hosted organizations have Loop logging disabled, and the setting doesn't appear for them.

## Enable Slack integration

Connect Slack to send alerts and notifications to your channels. Only members of the **Owners** [permission group](https://docs.braintrust.dev/admin/access-control.md), or a custom permission group with the **Manage settings** organization permission, can manage the Slack workspace connection.

1. Go to ** Settings** > [** Integrations**](https://www.braintrust.dev/app/~/configuration/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. Braintrust also sends Slack direct messages to assignees when spans or dataset rows are assigned to them for review, if they have linked their Slack accounts. See [Set up alerts](https://docs.braintrust.dev/observe/alerts.md), [Set up spend alerts](https://docs.braintrust.dev/admin/billing/monitor-usage.md#set-up-spend-alerts), and [Assign rows for review](https://docs.braintrust.dev/annotate/human-review/manage-review-work.md#assign-rows-for-review) 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.

### Braintrust link previews in Slack

When the Slack integration is enabled, Braintrust automatically expands links to logs, traces, and experiments that you paste into Slack. What each preview shows depends on whether you have linked your Slack account.

Supported link types:

* Log URLs.
* Trace URLs.
* Experiment URLs.

Braintrust shows a public preview with the resource title and description for all Slack users, including those who have not linked their account. Private resource details are only shown to Slack users who have linked their Slack account to a Braintrust account with access to the resource. To link your accounts, run `/braintrust link` in any Slack channel, or click **Link Braintrust account** in the prompt Braintrust sends when you open the Slack App Home or first interact with a link preview.

When you link from the App Home prompt and the Braintrust account you are signed in to uses a different email address than your Slack account, the authorization page displays a warning with a **Switch account** option. To unlink later, run `/braintrust unlink` in Slack.

## Set environment variables

Define secrets available to all functions in your organization:

1. Go to ** Settings** > [** Runtime**](https://www.braintrust.dev/app/~/configuration/runtime).
2. Under **Environment variables**, enter a name and value in the **Add a variable** form.
3. 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.

```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"]
```

## Configure API URLs (self-hosted)

> [!NOTE]
>
> Configuring custom data plane URLs is only available on the [Enterprise plan](https://docs.braintrust.dev/plans-and-limits.md#plans).

If your organization leaves the Enterprise plan, existing data plane URLs stay in effect, but you can no longer change them. This applies to both this settings page and the API.

For [self-hosted deployments](https://docs.braintrust.dev/admin/self-hosting.md), set custom API URLs:

1. Go to ** Settings** > [** Data plane**](https://www.braintrust.dev/app/~/configuration/data-plane).

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](https://docs.braintrust.dev/admin/data-management/retention.md) without requiring manual service token setup. You can view and manage this token in the [Service tokens](#create-service-tokens) section.

If another organization already uses the same self-hosted data plane, see [Add an organization to an existing data plane](https://docs.braintrust.dev/admin/self-hosting/configure/security.md#add-an-organization-to-an-existing-data-plane) before you use Loop, online scoring, or automations in the new organization.

> [!NOTE]
>
> Braintrust-hosted organizations (US or EU) can view their region and API URL in \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane).

## Set git metadata logging

Control which git metadata fields are logged:

1. Go to ** Settings** > [** Ingestion**](https://www.braintrust.dev/app/~/configuration/ingestion).
2. Under **Git metadata**, 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.

## Redact sensitive log data

[Ingestion redaction](https://docs.braintrust.dev/admin/data-management/protect-sensitive-data.md#redact-during-ingestion) detects and replaces sensitive text in incoming project logs. Create protected fields for one project or all projects in your organization. See [Create a protected field](https://docs.braintrust.dev/admin/data-management/protect-sensitive-data.md#create-a-protected-field) for setup and permissions. To hide fields from selected members when they read logs, without changing stored data, use [read rules](https://docs.braintrust.dev/admin/data-management/protect-sensitive-data.md#hide-fields-when-read).

## 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 ** Settings** > [** Runtime**](https://www.braintrust.dev/app/~/configuration/runtime).
2. Under **Image rendering**, select a 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.

> [!NOTE]
>
> Some image URLs are never loaded automatically, whichever mode you select. This covers URLs that name a host on your local or private network, such as `localhost`, a `.local` name, or a private or link-local IP address, and URLs using a scheme that a browser should never load an image from, such as `javascript:` or `file:`.
>
> In **Auto-load images** and **Click to load**, these images show a **Load image** button, so loading one is always a deliberate choice. In **Block all images**, they are blocked along with every other external image. Inline `data:` and `blob:` images are unaffected, because they never leave the browser.

## Configure environments

Create environments to version prompts and functions:

1. Go to ** Settings** > [** Environments**](https://www.braintrust.dev/app/~/configuration/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](https://docs.braintrust.dev/deploy/environments.md) 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](https://docs.braintrust.dev/admin/self-hosting.md#monitoring) for details.

## Delete an organization

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

## Next steps

* [Control access](https://docs.braintrust.dev/admin/access-control.md) with permission groups
* [Manage projects](https://docs.braintrust.dev/admin/projects.md) within your organization
* Manage organization configuration as code with the [Braintrust Terraform provider](https://docs.braintrust.dev/reference/terraform.md)
* [Use the Braintrust gateway](https://docs.braintrust.dev/deploy/gateway.md) for centralized provider access
* Set up [alerts](https://docs.braintrust.dev/observe/alerts.md) and [data management](https://docs.braintrust.dev/admin/data-management/export.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.