Skip to content
BuildBase
HTTP API menu

Base URLs, environments and CORS

Where to send BuildBase API requests - the cloud, a self-hosted server, a development or staging environment - and which browser origins may call it.

In short

Every request goes to a base URL followed by the operation's path. On BuildBase's cloud the base URL is always the same. If your company runs BuildBase on its own servers, it is that server's address. A development or staging environment uses the same address: what changes is the key or session you send, which belongs to that environment.

The base URL

Where BuildBase runsBase URL
BuildBase's cloudhttps://api.console.buildbase.app
Self-hostedYour tenant server's own public URL, the one its SERVER_URL setting names

A path from the reference goes straight after it:

curl -s "https://api.console.buildbase.app/api/v1/public/sessions" \
  -H "x-session-id: $BUILDBASE_SESSION_ID"

The OpenAPI document lists both as servers: the cloud first, then {serverUrl} for a self-hosted install. A self-hosted server's own copy of the spec, at GET <your server>/api/v1/openapi.json, names its own URL (The OpenAPI spec). Setting up a server: Self-hosting overview.

Environments

Production is your organization. Each non-production environment (Development, Staging...) is a separate tenant with its own database, users, sessions, API keys and webhooks, known to the API as <orgId>-<key>, where <key> is eight lowercase letters shown in the console. Production is the bare org id.

There is no environment header. A request reaches an environment through what it carries:

The request carriesIt reaches
A session (x-session-id)The environment the session was opened in
An API key (<id>:<secret>)The environment the key was made in. Make keys inside the environment
An org id in the path, query or bodyThat id: send <orgId>-<key> for an environment, the bare org id for production
curl -s "https://api.console.buildbase.app/.well-known/oauth-authorization-server/org/$BUILDBASE_ORG_ID-kxzpqwmr"

An id for an environment your organization does not have answers 404. Nothing crosses between environments: a session or a key works only in the environment it belongs to. The SDK builds the id with environmentId(); the whole picture is in Development and staging environments.

CORS: calling from a browser

PathsBrowser origins allowed
/api/v1/*, /.well-known/*, /org/*Any origin
Everything else under /api (the organization API)Only the server's own URL, BuildBase's apps, and, self-hosted, the origins in CORS_WHITELISTED_DOMAINS

On the open paths a preflight (OPTIONS) is answered for any origin and cached for two hours (Access-Control-Max-Age: 7200). The /api/v1 router allows these request headers:

Content-Type, Authorization, x-session-id, x-org-id, x-device-id, x-order-token, traceparent, tracestate, Idempotency-Key

Responses expose x-request-id to the page, so a browser can report which request failed.

The organization API answers no CORS headers to other origins, so a browser refuses to read it. That is on purpose: an API key belongs on your server, never in a page.

Next steps