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 runs | Base URL |
|---|---|
| BuildBase's cloud | https://api.console.buildbase.app |
| Self-hosted | Your 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 carries | It 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 body | That 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
| Paths | Browser 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-KeyResponses 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
- Authenticate API requests - the session and key each environment holds.
- Rate limits - limits count per address and per key.
- Development and staging environments - create one and promote changes.