Authentication

Braintrust authenticates in two directions: your users and services authenticate to Braintrust, and Braintrust authenticates outbound to model providers when it calls models on your behalf.

​

Authenticating to Braintrust

These are the ways users and services prove their identity to Braintrust.

​

End-user authentication

The most common form of authentication is end-user authentication to the Braintrust application. Users authenticate with your enterprise’s identity provider (e.g. Google, Okta) and receive credentials directly to their browser. In a self-hosted deployment, your API endpoints and data live in your own cloud environment, and these credentials communicate directly with the Braintrust API endpoint deployed in your cloud. You could even run these endpoints in a VPN that Braintrust’s servers can’t access, and the application will work.

​

Single sign-on (SSO)

Braintrust supports single sign-on (SSO) with your organization’s identity provider (powered by Clerk):

• Social login: Google.
• SAML: Okta Workforce, Microsoft Entra ID, Google Workspace, or a custom SAML provider.
• OpenID Connect (OIDC): A custom OIDC provider.

To get set up with SAML or OIDC SSO, contact Braintrust at support@braintrust.dev to exchange the appropriate configuration URLs. Once everything’s configured, Braintrust will turn it on for your domain and your team can start signing in using their regular work credentials.

​

Domain mappings

Domain mappings use just-in-time (JIT) provisioning to add users from specific email domains to your organization. On a successful sign-in, Braintrust adds the user without an invitation if they are not already an organization member. Domain mappings do not create accounts for everyone in a configured domain ahead of time. Each domain mapping matches one email domain and can optionally require one SAML group value. A matching mapping adds the user to one Braintrust organization and can optionally add them to one permission group. To match on a SAML group, configure your IdP to send each group as a separate value in the public_metadata_groups attribute. Braintrust applies a domain mapping only when the user first joins the organization. Later IdP group changes do not automatically update their Braintrust group membership. Users added this way still sign in through end-user authentication.

​

SCIM provisioning

Provision organization members from your identity provider instead of adding them by hand or by domain. Braintrust derives organization membership, and optionally permission group membership, from the SCIM groups a user belongs to.

​

API authentication

You can authenticate on behalf of users in your experiments or services using an API key. Braintrust API keys inherit their user’s permissions, and essentially are another way to authenticate as a user. To increase security, API keys are stored as one-way cryptographic hashes and cannot be recovered. The actual key is only displayed once upon creation. If you lose an API key, you will need to generate a new one (and can deactivate the old one). You can create an API key by going to Settings > API keys. When creating an API key or service token, you can optionally set an expiration, which cannot be changed after creation. After it expires, it stops authenticating and cannot be renewed, so create a new one to replace it. Keys created without an expiration will never expire.

​

MCP authentication

The Braintrust MCP (Model Context Protocol) server uses API key or OAuth 2.0 authentication, depending on the AI tool used to access the server. When AI tools use OAuth 2.0 to authentication, they:

1. Initiate an OAuth authorization flow.
2. Redirect users to authenticate with their Braintrust account.
3. Receive access tokens for API requests.
4. Use refresh tokens to maintain long-lived sessions.

This authentication method inherits your organization’s security policies and SSO configuration. MCP OAuth tokens follow the same permission model as your user account, providing access only to projects and resources you can normally access.

​

Authenticating to model providers

To make outbound calls to model providers on your behalf, Braintrust must authenticate with those providers. This is unrelated to how your users or services authenticate to Braintrust. By default, Braintrust authenticates to a model provider with a long-lived API key you store on the Settings > AI providers page. However, some providers allow Braintrust to obtain short-lived credentials at request time, eliminating the need to store long-lived credentials in Braintrust. Braintrust supports two such methods, depending on the provider:

• Workload identity federation: Braintrust exchanges a short-lived, Braintrust-signed OIDC token for a provider access token. Available for OpenAI, Anthropic, Google Vertex AI, and Azure AI Foundry.
• Assume role: Braintrust assumes an IAM role in your AWS account via the AWS STS AssumeRole, receives temporary credentials, and uses them to authenticate. Available for AWS Bedrock.

Both methods avoid storing a long-lived provider credential in Braintrust, but they rely on different flows: workload identity federation uses OIDC token exchange, while assume role uses AWS STS role assumption.