> ## 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 **Save**.
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 **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.
## 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
Organization members see both sections. Permissions control what you can change in each:
* Only members of the **Owners** [permission group](/docs/admin/access-control#built-in-permission-groups), or a custom permission group with the **Manage settings** organization permission, can add, edit, or delete providers under **Organization AI providers**. Everyone else sees the table in read-only mode.
* Only project members with the project-level **Update** permission can add, edit, or delete providers under **Project AI providers**. Everyone else sees the table in read-only mode.
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](/docs/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](/docs/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](/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.
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.
### GLM-5.2
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](/docs/deploy/gateway) by requesting model `glm-5.2`.
On Starter and Pro plans, GLM-5.2 usage 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, GLM-5.2 requires [on-demand usage](/docs/admin/billing/change-plan#enable-on-demand-usage) to be enabled, though your included credit still applies first.
## 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.