> ## 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.

# Authentication

> Understand how users and services authenticate to Braintrust, and how Braintrust authenticates to model providers on your behalf.

export const feature_1 = "Domain mappings"

export const verb_1 = "are"

export const feature_0 = "SAML and OIDC SSO"

export const verb_0 = "are"

export const FigmaEmbed = ({url}) => {
  return <iframe style={{
    border: "1px solid rgba(0, 0, 0, 0.1)",
    marginTop: "12px"
  }} width="100%" height="450" src={url} allowFullScreen />;
};

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](https://clerk.com/)):

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

<Note>
  {feature_0} {verb_0} only available on the [Enterprise plan](/plans-and-limits#plans).
</Note>

To get set up with SAML or OIDC SSO, contact Braintrust at [support@braintrust.dev](mailto: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.

In addition to matching email domains, domain mappings can optionally map SAML groups from the `public_metadata_groups` attribute to Braintrust groups when a user first signs in.

Users added this way still sign in through end-user authentication.

<Note>
  {feature_1} {verb_1} only available on the [Enterprise plan](/plans-and-limits#plans).
</Note>

### 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 **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys).

### MCP authentication

The [Braintrust MCP (Model Context Protocol)](/integrations/developer-tools/mcp) 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 <Tooltip tip="Short-lived tokens (typically 1 hour) used to authenticate API requests"> access tokens</Tooltip> for API requests.
4. Use <Tooltip tip="Long-lived tokens used to obtain new access tokens when they expire">refresh tokens</Tooltip> 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 **<Icon icon="settings-2" /> Settings** > [**<Icon icon="sparkle" /> AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets) 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](/integrations/ai-providers/openai), [Anthropic](/integrations/ai-providers/anthropic), [Google Vertex AI](/integrations/ai-providers/google), and [Azure AI Foundry](/integrations/ai-providers/azure).
* **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](/integrations/ai-providers/bedrock#connect-bedrock-to-braintrust).

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.

<Note>
  These short-lived credential methods are available only on Braintrust-hosted organizations, and workload identity federation additionally requires an [organization-level provider](/admin/ai-providers). Otherwise, such as on a self-hosted deployment, Braintrust authenticates with a stored API key instead.
</Note>