> ## 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.
# Configure AI providers
> Manage organization-level and project-level AI provider credentials for playgrounds, experiments, and the gateway.
Braintrust manages AI provider credentials on a single **AI providers** settings page. Configured providers are available in playgrounds, experiments, and the gateway without users needing individual API keys.
The page has two sections:
* **Organization AI providers**: defaults available across every project in the organization.
* **Project AI providers**: overrides for the currently selected project.
Each row shows a **Last updated** timestamp that tracks when the key value itself was last changed, along with the user who made the change. If you have permission to edit the section, each row also shows a redacted preview of the key (for example, `abc...xyz`). Renaming a provider or editing other metadata does not bump this timestamp. Keys that have not been rotated in over six months display a warning indicator. Braintrust recommends disabling and rotating AI provider secrets periodically.
## Add an organization-level provider
Organization-level keys serve as defaults across all projects in the organization.
1. Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).
2. Under **Organization AI providers**, click **Organization provider** and choose the provider you want to configure.
3. Enter your API key for that provider.
4. Click **Create**.
For provider-specific configuration (authentication methods, regions, model registries), see the [AI provider integrations](/docs/integrations/ai-providers).
### Authentication methods
Most providers authenticate with a long-lived API key. Some also support alternatives that avoid storing a long-lived provider credential in Braintrust:
* **Workload identity federation**: Braintrust exchanges a short-lived, Braintrust-signed OIDC token for a provider access token at request time, so no long-lived key is stored. Available for [OpenAI](/docs/integrations/ai-providers/openai), [Anthropic](/docs/integrations/ai-providers/anthropic), [Google Vertex AI](/docs/integrations/ai-providers/google), and [Azure AI Foundry](/docs/integrations/ai-providers/azure), for organization-level providers on Braintrust-hosted organizations with the gateway enabled.
* **Cloud-native role assumption**: [Bedrock](/docs/integrations/ai-providers/bedrock) supports AWS `AssumeRole` instead of storing long-lived access keys.
See each provider's integration page for setup details.
## Add a project-level provider
Use a project-level provider when:
* Different projects need separate billing or rate limits.
* You want to isolate API usage by project.
* Projects require different provider accounts or credentials.
* A project must use a specific regional endpoint (for example, US-specific OpenAI keys to keep traffic in-region).
1. Go to your project.
2. Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).
3. Under **Project AI providers**, click **Project provider** and choose the provider you want to configure.
4. Enter your API key for that provider.
5. Click **Create**.
You can also add a project-level provider inline from playgrounds within that project. When you attempt to run a playground without a configured provider, you'll see an option to add your API key without leaving the page.
## Update a provider
To change a configured provider's API key or other settings:
1. Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).
2. In the row for the provider you want to change, click the edit icon to open its edit sheet. You can also click the row itself.
3. Update the API key or other settings, then click **Update**.
Configured providers also appear in the **Organization provider** and **Project provider** pickers with a edit icon. Click a configured tile to edit it without leaving the picker. Custom providers appear only in the table, not the picker.
## Delete a provider
1. Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).
2. In the row for the provider you want to remove, click the delete icon. You can also open the provider's edit sheet and click **Delete** in the footer.
3. Confirm the deletion in the dialog that appears.
Deleting a provider immediately stops it from serving requests. Any gateway traffic or playground sessions relying on it fail until you configure another provider for those models.
## Custom providers
Braintrust supports custom AI providers at both the organization and project level. Add them from the same **Organization provider** or **Project provider** picker. See [Custom providers](/docs/integrations/ai-providers/custom) for endpoint configuration, headers, streaming, and cost metadata.
## How project overrides work
A request specifies a **model**, such as `gpt-4o`. To serve it, Braintrust:
1. Determines which providers are available to the project.
2. Routes the request to one of them that supports the requested model.
Project-level overrides affect only the first part: the project's provider set.
By default, every project can use the organization-level providers. When you add a project-level provider, Braintrust either replaces an organization-level provider or adds the new provider alongside it:
* Built-in providers override by **provider type**.
* Custom providers override by **exact name**, which is case-sensitive.
If the project-level provider matches an organization-level provider, it replaces that provider for the project, and the organization-level row shows an **Overridden** badge. For example, if the organization has an OpenAI provider and the project adds its own OpenAI provider, the project's provider replaces the organization's provider for that project.
On the [gateway](/docs/deploy/gateway), an overriding project-level provider fully replaces the organization-level provider. If a request specifies a model the project-level provider does not serve, the request fails instead of falling back to the organization-level provider. Make sure the overriding provider serves every model the project uses.
If the project-level provider does not match an organization-level provider, it is added alongside the existing providers. For example, a project-level custom provider named `Staging OpenAI` does not override an organization-level custom provider named `Production OpenAI`. Both remain available. Adding a differently named provider doesn't force Braintrust to use it, it just adds another eligible option.
| Goal | What to do |
| ---------------------------- | -------------------------------------------------------- |
| Override a built-in provider | Add a project-level provider with the same provider type |
| Override a custom provider | Add a project-level provider with the exact same name |
| Add another provider option | Use a different provider type or custom provider name |
Custom provider names are case-sensitive, so `OpenAI Proxy`, `openai proxy`, and `OpenAI proxy` are three different providers.
To confirm which provider served a request, check the `x-bt-used-endpoint` response header, which contains the name of the provider that handled it.
These rules describe the gateway. The legacy [AI proxy](/docs/deploy/ai-proxy) uses the same override rule, but applies it per model: a project-level provider overrides the organization-level one only for the models it serves. When several different-named providers are eligible for the same model, the proxy selects among them at random.
## Permissions and access
Use permissions to control who can use and manage your AI providers. At the organization level, permissions can apply to all providers or to a specific provider. At the project level, permissions control who can use and manage all project providers.
### Organization AI providers
Permissions can apply to all organization AI providers or to an individual provider:
Go to ** Settings** > [** Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups), then select a group.
Under **Organization**, the **Manage settings** permission lets group members add providers and edit them from the **AI providers** page.
Under **AI providers**, set the following permissions as needed:
* **Read** lets group members view and use providers anywhere Braintrust calls them, including playgrounds, experiments, scorers, and the [Gateway](/docs/deploy/gateway).
* **Update** lets group members rename a provider or change its configuration through the [API](/docs/api-reference).
* **Delete** lets group members delete providers.
* **Manage access** lets group members grant other permission groups access to providers.
Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets), then select the provider's **Provider permissions** icon.
On the **Permission groups**, **Members**, or **Service accounts** tab, select who receives access, then set the following permissions as needed:
* **Read** lets recipients view and use the provider anywhere Braintrust calls it, including playgrounds, experiments, scorers, and the [Gateway](/docs/deploy/gateway).
* **Update** lets recipients rename the provider or change its configuration through the [API](/docs/api-reference).
* **Delete** lets recipients delete the provider.
* **Manage access** lets recipients grant others access to the provider.
**Built-in permission groups**
To ensure continued provider access for existing accounts during the rollout of organization AI provider permissions, Braintrust created the **All AI Provider Access** group in every organization and added all existing members and service accounts to it. The group grants **Read** on every organization AI provider and no other permissions. New members are not added automatically.
Your plan determines which [permission groups](/docs/admin/access-control#built-in-permission-groups) you can assign accounts to:
* **Starter**: You can assign accounts only to **Owners**. Owners have all organization AI provider permissions.
* **Pro**: You can assign accounts to any built-in group. **Engineers**, **Viewers**, and **All AI Provider Access** grant **Read** on every organization AI provider.
* **Enterprise**: All built-in groups, plus custom groups. Custom groups can grant permissions across every organization AI provider or on individual providers.
Permissions are additive: a user or service account receives the combined access of every group they belong to. An account may therefore appear in **All AI Provider Access** even when another group also grants provider access. Before removing an account from **All AI Provider Access**, confirm it has **Read** access to each provider it needs through another permission group or a provider-specific permission.
**Service accounts**
Assign service accounts you create to permission groups that grant access to the providers they need. Each service token inherits the permissions of its service account.
Braintrust adds service accounts it provisions to **All AI Provider Access** so features such as online scoring and [Topics](/docs/observe/topics) can call organization-level AI providers. Removing these accounts from the group can prevent those features from working.
### Project AI providers
Project permissions apply to every provider in the project and do not affect access to organization-level providers. You cannot configure permissions for a specific project provider.
To configure a permission group's ability to use or manage project-level AI providers:
* Go to the project's ** Settings** > [** Project permissions**](https://www.braintrust.dev/app/~/configuration/permissions), then select a permission group.
* Under **Project**:
* **Read** lets group members view the project and use all its AI providers.
* **Update** lets group members add, edit, and delete project-level AI providers. To allow provider use without allowing changes, grant **Read** but not **Update**.
The **Update** permission controls project resources other than AI providers. Review [What `Update` covers](/docs/admin/access-control#what-update-covers) before removing it.
## Manage built-in models
Braintrust serves a set of models that your organization can use without configuring its own AI provider. They back the built-in model choices in playgrounds, prompts, and scorers, the models that [Loop](/docs/loop) and [Patterns](/docs/observe/patterns) run on, and the facet summarization, embeddings, and cluster naming behind [Topics](/docs/observe/topics).
### Available models
In playgrounds, prompts, and scorers, you can select these models from the **Braintrust** provider. When your organization has no AI providers configured, GLM-5.2 is selected by default. You can also call each model through the [gateway](/docs/deploy/gateway) by requesting the model ID below.
| Model | Model ID |
| ---------------------- | ------------------------ |
| GLM-5.2 | `glm-5.2` |
| GLM-5.3 Flash | `glm-5.3-flash` |
| Kimi K3 | `kimi-k3` |
| DeepSeek V4 Flash 0731 | `deepseek-v4-flash-0731` |
Loop and Patterns run on three further built-in models, GPT-5.6 Sol, GPT-5.6 Terra, and GPT-5.6 Luna. You select them from Loop's model picker rather than from the **Braintrust** provider, and they aren't available in playgrounds, prompts, or scorers. See [Choose a provider and model](/docs/loop#choose-a-provider-and-model).
Topics runs on a family of `brain-*` models that Braintrust selects for you. They aren't selectable anywhere in the product.
### Requirements
Using a built-in model requires both of the following:
* **Built-in models are allowed for your organization.** Braintrust-hosted organizations have them on by default. Self-hosted organizations have them off by default, so that no trace data leaves your network boundary, and must turn them on first.
* **On the Starter plan, an eligible owner or a payment method.** Your organization needs at least one owner with a work email address, or a payment method on file. Braintrust checks the email domain of each [organization owner](/docs/admin/access-control#built-in-permission-groups) against a maintained list of personal email providers.
The Starter requirement covers every built-in model you can select: the four open-source models in playgrounds, prompts, and scorers, and the three GPT-5.6 models that Loop and Patterns run on. Topics' `brain-*` models are exempt.
Until your organization qualifies, the affected models don't appear in any model picker, and gateway requests for them return HTTP 403. To qualify, [add a payment method](/docs/admin/billing/change-plan#enable-on-demand-usage), or add an organization owner whose email uses a work domain. Access resumes as soon as ownership changes.
### Enable or disable built-in models
1. Go to ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).
2. Under **Built-in models**, turn **Allow built-in models** on or off.
Disabling built-in models forces Loop to run on your own AI providers. Loop's **Built-in** setting is unavailable until you re-enable them. See [Models and providers](/docs/loop/manage#models-and-providers).
Disabling built-in models automatically pauses your topic automations. Re-enabling built-in models does not automatically resume them. You must [resume](/docs/observe/topics/manage#pause-resume-automation) each automation manually.
Only members of the **Owners** [permission group](/docs/admin/access-control), or a custom permission group with the **Manage settings** organization permission, can enable or disable built-in models.
### Cost and credits
On Starter and Pro plans, usage of built-in models draws down your [model credits](/docs/plans-and-limits#usage-limits), shared with Topics, and continues at the [on-demand token rates](/docs/plans-and-limits#model-credits) once your credits are exhausted. On Starter, they become unavailable once you use up the credit, until you [enable on-demand usage](/docs/admin/billing/change-plan#enable-on-demand-usage) or upgrade to Pro. Pro and on-demand usage continue at the same rates beyond the credit.
### Data handling
Braintrust hosts the `brain-*` models on [Baseten](https://www.baseten.co/), which is included in the Braintrust [DPA](https://www.braintrust.dev/legal/dpa) as a subprocessor. These endpoints run with Zero Data Retention (ZDR) for every organization, whether Braintrust-hosted (SaaS), [BYOC](/docs/admin/deployment/byoc), or self-hosted. ZDR is on by default and requires no configuration, so inference inputs and outputs are not stored by the model host. See Baseten's [data privacy documentation](https://docs.baseten.co/observability/security#data-privacy).
## Next steps
* Browse [supported AI providers](/docs/integrations/ai-providers) for provider-specific configuration.
* [Manage permissions](/docs/admin/access-control/manage-permissions) to control who can add or modify project-level AI providers.