Learn how to authenticate your requests to the BuildBetter GraphQL API and where to send them.
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).
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.)
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).