​
Authentication & Endpoint Setup

​
Authentication

All requests to the BuildBetter GraphQL API must be authenticated. 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) and the GraphQL request will not be executed. API keys and tokens should be kept secret – do not expose them in client-side code or public repositories.

​
GraphQL Endpoint

The BuildBetter GraphQL API endpoint is a single URL that accepts GraphQL queries, mutations, and subscriptions. The base URL for the GraphQL endpoint is:

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

All GraphQL HTTP requests (queries and mutations) should be sent as POST requests to this URL. For example, you might send a JSON payload like:

{
  "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).