Skip to main content
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.
  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.

​
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, Anthropic, Google Vertex AI, and Azure AI Foundry, for organization-level providers on Braintrust-hosted organizations with the gateway enabled.
  • Cloud-native role assumption: 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.
  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.
  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 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, 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. 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 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, 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.
  • Update lets group members rename a provider or change its configuration through the API.
  • Delete lets group members delete providers.
  • Manage access lets group members grant other permission groups access to providers.
Go to Settings > AI providers, 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.
  • Update lets recipients rename the provider or change its configuration through the API.
  • 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 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 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, 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 before removing it.

​
Manage built-in models

Topics use a family of Braintrust-served models (brain-*) for facet summarization, embeddings, and cluster naming. Braintrust hosts these models on Baseten, which is included in the Braintrust DPA as a subprocessor. These endpoints run with Zero Data Retention (ZDR) for every organization, whether Braintrust-hosted (SaaS), 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. 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.
  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 each automation manually.
Only members of the Owners permission group, 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 > 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 by requesting the model ID below. On Starter and Pro plans, usage of these models draws down your model credits, shared with Topics, and continues at the on-demand token rates once your credits are exhausted. On Starter, they become unavailable once you use up the credit, until you enable on-demand usage or upgrade to Pro. Pro and on-demand usage continue at the same rates beyond the credit.

​
Next steps