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

Automatically add users from specific email domains to your organization. Domain mappings control who can join your organization. Users added this way still sign in through end-user authentication. To get set up, contact Braintrust at support@braintrust.dev.

​

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.

​

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

This direction is the opposite of the sections above: how Braintrust authenticates outbound to model providers when it calls models on your behalf. This does not change 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 AI providers page. As an alternative, some providers support workload identity federation, where Braintrust exchanges a short-lived, Braintrust-signed OIDC token for a provider access token, so no long-lived provider key is stored in Braintrust. Workload identity federation is available for OpenAI, Anthropic, Google Vertex AI, and Azure AI Foundry.