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

# Authentication

> Authenticate Bulkgrid API requests with the x-api-key header.

Bulkgrid uses API key authentication on every current endpoint.

## Send the API key in `x-api-key`

<CodeGroup>
  ```bash cURL theme={null}
  curl https://your-bulkgrid-base-url/api/v1/search \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: bg_live_your_api_key' \
    -d '{"query":"release notes"}'
  ```

  ```js Node.js theme={null}
  import { BulkgridClient } from '@bulkgrid/sdk';

  const client = new BulkgridClient({
    apiKey: process.env.BULKGRID_API_KEY ?? '',
    baseUrl: process.env.BULKGRID_BASE_URL ?? '',
  });

  const response = await client.search({ query: 'release notes' });
  ```
</CodeGroup>

## Recommended environment variables

```bash theme={null}
export BULKGRID_API_KEY='bg_live_your_api_key'
export BULKGRID_BASE_URL='https://your-bulkgrid-base-url'
```

## What to avoid

* Do not expose Bulkgrid API keys in browser code.
* Do not treat the key as a bearer token.
* Do not assume proxies preserve custom headers unless you control that path.

## Common failures

### `401 Unauthorized`

This usually means the `x-api-key` header is missing, malformed, or invalid.

Example error shape:

```json theme={null}
{
  "error": "Unauthorized"
}
```

### Requests work locally but fail in production

Check these first:

* the deployed service is using the right environment variables
* the request is being sent to the correct Bulkgrid base URL
* no gateway, CDN, or proxy is stripping `x-api-key`

## Recommended integration pattern

Call Bulkgrid from your backend or worker layer, not directly from the browser.