> ## 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.
## 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
[Topics](/docs/observe/topics) use a family of Braintrust-served models (`brain-*`) for facet summarization, embeddings, and cluster naming. Braintrust hosts these 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).
For Braintrust-hosted (SaaS) organizations, built-in models are enabled by default. For self-hosted organizations, built-in models are disabled by default so that no trace data leaves your network boundary. Self-hosted organizations must enable built-in models to use Topics.
To 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.
Loop is unaffected by this setting. Its chat models always come from your configured AI 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.
### Open-source models
Braintrust serves a set of open-source reasoning models that you can use without configuring your own AI provider. They're available whenever ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets) > **Allow built-in models** is enabled, which is the default for Braintrust-hosted organizations. Self-hosted organizations have built-in models disabled by default and must enable them first. On the Starter plan, your organization also needs at least one owner with a work email address, or a payment method on file.
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` |
| Kimi K3 | `kimi-k3` |
| DeepSeek V4 Flash 0731 | `deepseek-v4-flash-0731` |
On Starter and Pro plans, usage of these 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.
## 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.