> ## 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 redacted preview of the key (for example, `abc...xyz`) and a **Last updated** timestamp that tracks when the key value itself was last changed, along with the user who made the change. 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 **Save**.
For provider-specific configuration (authentication methods, regions, model registries), see the [AI provider integrations](/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](/integrations/ai-providers/openai), [Anthropic](/integrations/ai-providers/anthropic), [Google Vertex AI](/integrations/ai-providers/google), and [Azure AI Foundry](/integrations/ai-providers/azure), for organization-level providers on Braintrust-hosted organizations with the gateway enabled.
* **Cloud-native role assumption**: [Bedrock](/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 **Save**.
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.
## 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](/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](/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](/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
Visibility of the two sections depends on the role of the signed-in user:
* **Organization admins** see both **Organization AI providers** and **Project AI providers**.
* **Project admins** with only the project-level **Update** permission see just **Project AI providers**.
* Project members without **Update** don't see the **Project AI providers** section at all.
Adding or modifying a project-level provider requires the **Update** permission, which governs modifying project resources in general. To keep all LLM traffic on approved organization-configured providers (for example, Bedrock) and prevent project users from adding their own keys:
1. In your project, go to ** Settings** > [** Project permissions**](https://www.braintrust.dev/app/~/configuration/permissions).
2. Remove the **Update** permission from non-admin users or their permission groups. Without **Update**, they can't add or modify project-level AI providers.
3. To preserve normal project work, [create a permission group](/admin/access-control/manage-permissions#create-custom-permission-groups) that grants **Read**, **Create**, and **Delete** but not **Update**, then assign those users to it.
For everything `Update` controls, see [What `Update` covers](/admin/access-control#what-update-covers).
Removing **Update** doesn't cut off access to organization-level providers. Those stay available to every user for playgrounds, experiments, and the gateway, regardless of project permissions.
API keys are stored as one-way cryptographic hashes, never in plaintext.
## Manage built-in models
[Topics](/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.
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](/observe/topics/manage#pause-resume-automation) each automation manually.
Only members of the **Owners** [permission group](/admin/access-control), or a custom permission group with the **Manage settings** organization permission, can enable or disable built-in models.
### GLM-5.2
GLM-5.2 is available for a limited time, through July 31, 2026.
GLM-5.2 is an open-source reasoning model, accessible from Braintrust without configuring your own AI provider. It's available to Braintrust-hosted organizations (not self-hosted), but only when ** Settings** > [** AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets) > **Allow built-in models** is enabled (this setting is enabled by default for Braintrust-hosted organizations).
In playgrounds, prompts, and scorers, you can select GLM-5.2 from the **Braintrust** provider. When your organization has no AI providers configured, it's selected by default. You can also call GLM-5.2 through the [gateway](/deploy/gateway) by requesting model `glm-5.2`.
On Starter and Pro plans, GLM-5.2 usage draws down your [monthly credit](/plans-and-limits#glm-5-2-usage), shared with Topics, at \$1.40 per million input tokens, \$4.40 per million output tokens, and \$0.26 per million cached input tokens. On Starter, GLM-5.2 is available once you [enable on-demand usage](/admin/billing/change-plan#enable-on-demand-usage), and your included credit still applies first. Usage beyond the credit continues at the same rates.
## Next steps
* Browse [supported AI providers](/integrations/ai-providers) for provider-specific configuration.
* [Manage permissions](/admin/access-control/manage-permissions) to control who can add or modify project-level AI providers.