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

> Choose API keys or OAuth and understand workspace and collection access.

Bulkgrid supports API keys for backend integrations and OAuth for AI apps and CLI connections. Every connection is limited to a workspace and its granted permissions.

| Connection             | Authentication           | Access                                                 |
| ---------------------- | ------------------------ | ------------------------------------------------------ |
| Backend service or SDK | API key                  | Scopes selected when creating the key                  |
| AI app over MCP        | Browser OAuth or API key | MCP tools and permitted search content                 |
| Bulkgrid CLI login     | Browser OAuth            | `mcp:use` and `search:query` in the approved workspace |

## API keys

Create a key in [Settings → API Keys](https://bulkgrid.com/dashboard/settings/api-keys). Workspace owners and admins can create, rotate, and revoke keys. Use separate keys for development and production.

Both headers are supported. Send one authentication method per request:

Node.js and Python examples use the [Bulkgrid SDKs](/docs/sdk). Set `BULKGRID_API_KEY` in your backend environment; cURL examples also use `BULKGRID_BASE_URL=https://bulkgrid.com`.

<CodeGroup>
  ```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 ?? 'https://bulkgrid.com',
  });

  const data = await client.search({
    query: 'release notes',
  });
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  from bulkgrid import BulkgridClient

  with BulkgridClient(
      api_key=os.environ["BULKGRID_API_KEY"],
      base_url=os.environ.get("BULKGRID_BASE_URL", "https://bulkgrid.com"),
  ) as client:
      data = client.search({"query": "release notes"})
      print(data)
  ```

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

The equivalent bearer header is:

```text theme={null}
Authorization: Bearer bg_live_your_api_key
```

The [TypeScript SDK](/docs/sdk) sends the key through `x-api-key`. See [API key scopes](/docs/api-key-scopes) for permissions required by each workflow.

## OAuth connections

Add `https://bulkgrid.com/api/v1/mcp` to a compatible AI client, or run `bulkgrid login` from the [CLI](/docs/cli).

Your browser opens Bulkgrid's consent page. Sign in if needed, select the workspace and collection access, and approve the connection. Your current workspace is preselected when available. The client receives tokens and handles refresh.

OAuth access tokens are sent as `Authorization: Bearer <access-token>`. They currently grant `mcp:use` and `search:query`; they do not authorize creating runs, managing sources, or fetching arbitrary run results. Use a suitably scoped API key for those operations.

## Workspace and collection boundaries

API keys belong to a workspace. An OAuth user/client connection is bound to the workspace selected during consent. Reauthorizing the same connection retains that workspace.

Keys and OAuth grants can allow all accessible collections or selected collections. A `collectionId` search filter can narrow access; it cannot grant access beyond the credential's permissions. OAuth access also requires the user to remain a member of the workspace.

CLI login and an AI app's MCP login are separate connections.

Manage OAuth connections under **Settings → Connected Apps**. Revocation blocks subsequent Bulkgrid API access. CLI users can also run `bulkgrid logout`.

## Errors

| Status | Check                                                                                         |
| ------ | --------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or expired credentials; correct server URL; preserved authentication header |
| `403`  | Required scope, workspace membership, collection access, revoked connection, or plan limit    |

Keep API keys and refresh tokens out of browser bundles, source control, and logs. Your application backend should hold service credentials.