# 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](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:

```bash
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](/http-api/openapi)). Setting up a server: [Self-hosting overview](/self-hosted/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 |

```bash
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](/quick-start/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:

```text
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

- [Authenticate API requests](/http-api/authentication) - the session and key each environment holds.
- [Rate limits](/http-api/rate-limits) - limits count per address and per key.
- [Development and staging environments](/quick-start/environments) - create one and promote changes.
