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

# Authentication & Endpoint Setup

> Learn how to authenticate your requests to the BuildBetter API.

## Authentication

All BuildBetter API requests must be authenticated. REST is the supported path for new customer integrations.

<Warning>
  The GraphQL API is being deprecated for customer integrations. Use REST endpoints for new integrations and migrate existing GraphQL workflows to REST.
</Warning>

You can authenticate in one of two ways:

* **API Key (Header):** Provide your API key in the HTTP header `X-Buildbetter-API-Key`. For example: `X-Buildbetter-API-Key: YOUR_API_KEY`. This method is typically used for server-to-server access or integration scenarios. An API key may be scoped to an organization or a specific shared object (like a particular call or document), so it grants access according to its scope (e.g. all data in your organization or just one shared call/document).

* **Bearer Token (Header):** If you have a user login token (JWT), include it in the `Authorization` header as a Bearer token. For example: `Authorization: Bearer YOUR_JWT_TOKEN`. This method is used for authenticated user access. The token will be validated by the API, and if valid, the request will execute with the permissions of that user. (If your user account belongs to multiple organizations, you may also include an `X-Buildbetter-Organization-Key` header to specify which organization's context to use for the query, though in most cases this is not needed unless explicitly working across organizations.)

**Note:** Ensure you include *one* form of authentication on every request. If no valid API key or token is provided, the API will return an **Unauthorized** error (HTTP 401). API keys and tokens should be kept secret – do not expose them in client-side code or public repositories.

## REST Endpoint

The base URL for REST endpoints is:

```text theme={null}
https://api.buildbetter.app/v3/rest
```

For example, recording reads are available under `/recordings/{recordingId}`. See [Recordings API](/pages/api/recordings).

## Legacy GraphQL Endpoint

The BuildBetter GraphQL API is deprecated for customer integrations. Existing integrations may still use the legacy GraphQL endpoint during migration:

```
https://api.buildbetter.app/v1/graphql
```

Legacy GraphQL HTTP requests should be sent as POST requests to this URL. For example, you might send a JSON payload like:

```json theme={null}
{
  "query": "query { ... }",
  "variables": { ... }
}
```

to `https://api.buildbetter.app/v1/graphql`. The API will respond with a JSON object containing your query results or errors.

For real-time updates, the API also supports GraphQL subscriptions over WebSocket. The WebSocket endpoint is the same except with the `wss://` protocol. For example, `wss://api.buildbetter.app/v1/graphql` is used for subscriptions. (In a web app using Apollo or similar, you would configure the WebSocket URI for subscriptions accordingly.)

**CORS:** The GraphQL endpoint is CORS-enabled for allowed origins. When making requests from a browser or frontend app, ensure your origin is allowed. By default, the endpoint will accept requests from BuildBetter's domains (and in development, it may be configured to accept localhost).