> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding 401 errors with OpenAI provider auth

> Fix 401 errors from OpenAI embedding calls by setting the provider auth_format to bearer and including the correct request headers in Braintrust Gateway.

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> * Use case - Troubleshoot OpenAI embedding authentication errors.

## Summary

Embedding requests to `text-embedding-3-small` can return upstream 401 errors when the selected native OpenAI provider is configured with `auth_format: "api_key"`. Set the provider's authorization format to `"bearer"` and retry. Include `x-bt-project-id` when you need project-level providers. Changing the auth format resolves this misconfiguration. Adding routing headers alone does not.

## What is happening

The client authenticates to the Gateway using `Authorization: Bearer <BRAINTRUST_API_KEY>`. The Gateway then uses the selected provider's stored OpenAI key and `auth_format` to authenticate upstream. OpenAI expects bearer authentication, so `auth_format: "api_key"` can cause embedding requests to fail even when other OpenAI calls succeed. By default, the Gateway uses organization-level providers. Including `x-bt-project-id` makes that project's providers available, with provider selection determined by the Gateway's routing rules.

## Fix or suggestion

### Option 1: change provider `auth_format` to `bearer`

1. Go to ** Settings** > [** Models**](https://www.braintrust.dev/app/~/configuration/models/organization).
2. Select the **Organization** or **Project** tab to match the provider's scope, then open the OpenAI provider used by the failing request.
3. On the **Setup** tab, expand **More settings** if it is collapsed, and select **Form**.
4. Set **Authorization header format** to **Bearer**. If you authenticate with an OpenAI API key, keep **API key** selected as the authentication method.
5. Click **Save**.
6. If you need project-level providers, include `x-bt-project-id` on embedding requests and retry.

If you use **Raw** instead of **Form**, change only `auth_format` from `"api_key"` to `"bearer"` in your existing provider configuration. Preserve its credentials, API base URL, and other settings. The following excerpts illustrate the change.

Before:

```json theme={null}
{
  "name": "openai-org",
  "auth_format": "api_key",
  "api_base": "https://api.openai.com/v1",
  "api_key": "<api_key>"
}
```

After:

```json theme={null}
{
  "name": "openai-org",
  "auth_format": "bearer",
  "api_base": "https://api.openai.com/v1",
  "api_key": "<api_key>"
}
```

Example embedding request through the Gateway. Replace the project ID with your own, and include that header when you need project-level providers.

```http theme={null}
POST https://gateway.braintrust.dev/v1/embeddings
Content-Type: application/json
Authorization: Bearer <BRAINTRUST_API_KEY>
x-bt-project-id: <x-bt-project-id>

{"model":"text-embedding-3-small","input":["ok"]}
```

### Option 2: verify headers and provider routing

1. Confirm the request includes `Authorization: Bearer <BRAINTRUST_API_KEY>`.
2. For troubleshooting, temporarily remove `x-bt-fallback-providers` and other optional routing headers to simplify the request. Their presence alone does not establish the cause of a 401.
3. Confirm the selected provider's `api_base` matches the OpenAI endpoint you expect.
4. Organization-level providers do not require `x-bt-project-id`. Include it when you need the Gateway to consider project-level providers.

## How to confirm it worked

* A successful embedding request returns HTTP 200 and, with the default float encoding, an embedding vector in `data[0].embedding`.
* Check logs or request traces and confirm the retried embedding request returned a 200 status for the intended model and provider.

## Notes

* To verify supported models, see [Supported models](https://docs.braintrust.dev/deploy/supported-models.md).
* Keep API keys and secrets out of logs and UI screenshots. Replace actual keys with placeholders when sharing request examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.