Skip to main content
Braintrust manages AI provider credentials on the Settings > AI providers page, so you can share access without each team member needing an individual API key. Most configured providers are available in playgrounds, experiments, and the gateway. AI providers can be configured at two scopes:
  • Organization AI providers are the defaults available across every project in the organization.
  • Project AI providers are configured for the selected project. They can override matching organization providers or provide additional options.
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 a provider

For provider-specific configuration (authentication methods, regions, model registries), see the AI provider integrations.

​
Organization providers

Organization providers make credentials available across projects, subject to provider permissions.
  1. Go to Settings > AI providers.
  2. Under Organization AI providers, click Organization provider and choose the provider you want to configure.
  3. On Setup, enter your API key or configure another supported authentication method. Complete any required provider settings, such as the endpoint or region.
  4. Open More settings to configure request settings, additional headers, and model restrictions.
  5. Click Create. The sheet opens on Models, where you can browse models and test a request.

​
Project providers

Project providers let you configure credentials for a specific project. Use them when you need separate billing or rate limits, isolated API usage, different provider accounts or credentials, or a specific regional endpoint (for example, US-specific OpenAI keys to keep traffic in-region). To add a provider for your project:
  1. In your project, navigate to Settings > AI providers.
  2. Under Project AI providers, click Project provider and choose the provider you want to configure.
  3. On Setup, enter your credentials and complete any required settings for the provider. See the AI provider integrations for provider-specific instructions.
  4. Open More settings to configure request settings, additional headers, and model restrictions.
  5. Click Create. The sheet opens on Models, where you can browse models and test a request.
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 for endpoint configuration, headers, streaming, and cost metadata.

​
Authentication

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.

​
Update a provider

To change a configured provider’s API key or other settings:
  1. Go to Settings > AI providers.
  2. In the row for the provider you want to change, click the edit icon, or click the row itself.
  3. On the Setup tab, update the API key or other settings.
  4. Open More settings, if collapsed, to configure request settings, additional headers, and model restrictions.
  5. Click Update. The sheet opens on Models.
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.
  2. In the row for the provider you want to remove, click the delete icon. You can also open the provider’s Setup tab and click Delete in the footer.
  3. Confirm the deletion in the dialog that appears.
Deleting a provider removes its credentials and configuration. Requests that rely on the provider fail unless another eligible provider can handle them.

​
Browse and test models

Open a configured provider to see its models and test a request through the Gateway.
  1. Go to Settings > AI providers.
  2. Click the provider’s row, then select Models. If you don’t have permission to edit the provider, the sheet opens on Models and Setup is disabled.
  3. Under Available models, search by model name or ID.
  4. Choose a model from the selector above the request example.
  5. Use an existing Braintrust API key in place of $BRAINTRUST_API_KEY, or click Generate API key, enter a name, and click Create API key. The generated key is a Braintrust API key and is inserted into the command.
  6. Copy the curl command and run it in your terminal. The command requests the selected model through this provider. For a project provider, it also includes the project’s ID. A successful request returns a model response.
The list includes models Braintrust supports for this provider, filtered by the model restrictions you’ve configured, plus any custom models you’ve added. It excludes deprecated and embedding models, and does not verify which models your upstream provider account can access. Run a request to confirm access to a specific model. If no models are listed, the request example is unavailable. If you can edit the provider, check its model restrictions or add a Custom model on Setup, then save the configuration.
Gateway requests use the permissions of the user or service account that owns the Braintrust API key. Generating a key does not grant additional provider access. See Permissions and access.

​
Request routing

Multiple organization and project providers can be configured to handle requests that target the same model. When a request arrives, it specifies a particular model. Braintrust determines which providers are eligible to handle the request, then selects one to handle it.

​
Provider eligibility

First, Braintrust determines which organization and project providers are eligible to handle the incoming request. To be eligible, a provider must support the requested model, allow it under its model restrictions, and be accessible to the caller through provider permissions. Project providers can also make matching organization providers ineligible, as described below. Consider the following scenarios:
  • organization and project providers both support and allow the requested model The project provider remains eligible, and the organization provider becomes ineligible.
  • An organization provider supports and allows the requested model, but a project provider does not Whether the organization provider remains eligible depends on your deployment:
    • Braintrust-hosted: The project provider is ineligible because it does not support the requested model or excludes it under model restrictions. The organization provider remains eligible. (Therefore, excluding a model through a project provider’s model restrictions does not block access to that model through an organization provider the caller has permission to use.)
    • Self-hosted: The project provider does not support the requested model or excludes it under model restrictions. It still overrides the organization provider, making both ineligible. The request fails unless another eligible provider can handle the request.
    The legacy AI proxy excludes a matching organization provider only when the project provider supports and allows the requested model. In this scenario, the organization provider remains eligible.
  • organization and project providers both support and allow the requested model Both providers remain eligible for the request. Neither overrides the other, and the project provider does not automatically take priority. For example, a project-level custom provider named Staging OpenAI does not override an organization-level custom provider named Production OpenAI. If both support and allow gpt-5-mini and the caller can use both, both remain eligible for the request.
When an organization provider has a project provider, the organization provider’s row in Settings > AI providers displays an Overridden badge. Model restrictions do not affect the badge, so the badge does not indicate which provider handles a particular request.

​
Provider selection

Braintrust selects a provider from those eligible for the request. If multiple providers are eligible, Braintrust selects one automatically.
The legacy AI proxy randomly selects an eligible provider for the first attempt. If that attempt fails, the proxy can retry with other eligible providers.
Specify a particular provider To specify which provider should handle a given request, set the x-bt-endpoint-name header to the provider’s configuration name, as shown on the provider’s row in Settings > AI providers: For built-in providers, use the identifier displayed beneath the provider’s friendly name. For custom providers, use the exact name, including capitalization. The command in the provider’s Models tab includes the correct header value. This header selects a provider by name, not by organization or project scope. If a project provider overrides an organization provider with that name, the routing rules above still apply. Specifying a provider does not bypass permissions or model restrictions. To confirm which provider handled a request, check the x-bt-used-endpoint response header, which contains the name of the provider that handled it.

​
Restrict available models

Model restrictions let you choose which models a provider allows. Combined with provider permissions, these restrictions let you control which models members and service accounts can use.
  1. If you’re restricting a project-level provider, make sure you’re in that project.
  2. Go to Settings > AI providers.
  3. Click the provider’s row, then select Setup.
  4. Expand More settings.
  5. Under Models, set Registry models:
    • All models: Include all models in Braintrust’s registry for this provider.
    • Selected models: Include only the registry models you select. Search the list and check each model you want to allow.
    • None: Exclude registry models. Only models you add with Custom model remain available.
  6. Click Update to save the configuration, or Create if you are adding a provider.
When configuring model restrictions, keep the following in mind:
To edit an organization provider in the UI, you need the organization’s Manage settings permission. To edit a project provider, you need the project’s Update permission. The Update permission on an organization provider allows API changes but does not grant editing access in this UI. See Permissions and access.
Organization providers support model restrictions on both Braintrust-hosted and self-hosted deployments. For project providers, Selected models is available on Braintrust-hosted deployments. Self-hosted deployments support All models and None, along with custom models.
Custom models remain available in all three modes. To remove a custom model, remove its entry from the provider’s configuration. None does not disable the provider or remove its custom models.
Before excluding a model, check whether any playgrounds or LLM scorers use it, including scorers used for online scoring. Their model requests may fail unless another eligible provider can handle those requests.

​
Combine model restrictions with permissions

Model restrictions determine which models a provider allows, while provider permissions determine who can use that provider. On Enterprise, you can combine them to give teams access to different model selections. To set this up:
  1. Create separate organization provider configurations for the model selections each team needs. If teams need different model selections from the same upstream provider, create separate custom providers with distinct names.
  2. Set each provider’s model restrictions to allow only the models that team should use.
  3. In organization provider permissions, grant each team’s permission group Read access to that team’s provider. This lets members use the models allowed by that provider.
Permissions are additive. To ensure each team can access only the intended models, also check:
Restricting a team’s provider does not prevent members from using a model through another organization provider they can access. For example, membership in All AI Provider Access grants Read access to every organization provider, including providers that allow models outside the team’s intended set.
Restricting an organization provider does not restrict access through project providers. If a project provider allows a model excluded from the team’s organization provider, members with Read access to that project can still use the model through the project provider.
Braintrust built-in models are available without configuring your own provider credentials. Restrictions on your configured providers do not control access to these models. Disable Allow built-in models in Settings > AI providers if members should use only your configured providers.

​
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

Braintrust provides 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 and Patterns run on, and the facet summarization, embeddings, and cluster naming behind 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 by requesting the model ID below. Loop and Patterns run on GPT-6 Astra, GPT-5.6 Sol, GPT-5.6 Terra, and GPT-5.6 Luna as built-in models. 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. 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 against a maintained list of personal email providers.
The Starter requirement covers every built-in model you can select: the open-source models in playgrounds, prompts, and scorers, and the 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, 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.
  2. Under Built-in models, turn Allow built-in models on or off.
Jev needs a second opt-in of its own. With built-in models allowed, click Enable Jev and agree to send data submitted to Jev to TypeSafe for processing. The same permission requirement below applies to that setting. Disabling built-in models forces Loop to run on your own AI providers. Braintrust does not appear as a provider option in Loop until you re-enable built-in models. See 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 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.

​
Cost and credits

Built-in Jev is free to use and does not consume model credits. The following billing rules apply to other built-in models. On Starter and Pro plans, usage of built-in 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.

​
Data handling

Braintrust hosts GLM-5.2, GLM-5.3 Flash, Kimi K3, DeepSeek V4 Flash 0731, DeepSeek V4.1 Flash, and the brain-* models behind Topics 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. Jev is the exception. It runs on TypeSafe rather than Baseten, so the terms above do not describe how that data is handled, and your organization has to opt in before anyone can select it. Enabling Jev requires agreeing that data submitted to Jev is sent to TypeSafe for processing. When you run a model through one of your own AI providers instead, the request goes to that provider on your own key. Your agreement with that provider, including any ZDR agreement, governs the prompt and the response.

​
Next steps