Getting Started

Authentication

BrowseFleet runs without authentication by default. When you set the API_KEYS environment variable, every request must carry a matching x-api-key header.

Configuring keys

Set API_KEYS on the server to a comma-separated list of secrets. If the variable is empty or unset, authentication is disabled and all requests are accepted; only do this on a host bound to localhost or behind another auth layer.

# Authentication on, two valid keys
API_KEYS=bf_key_one,bf_key_two

# Authentication off (default; only safe on localhost)
API_KEYS=

Generate keys however you want. The server treats them as opaque strings. A common pattern: prefix with bf_ and append 32 hex characters, e.g. bf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4.

REST requests

Pass the key in the x-api-key header on every request. The SDKs read it from BROWSEFLEET_API_KEY if you do not pass it explicitly.

curl http://localhost:3000/v1/sessions \
  -H "x-api-key: bf_your_api_key"

CDP WebSocket

For CDP connections, pass the key as a query parameter. Use the websocketUrl the create-session endpoint returns; the SDKs construct it correctly for you.

ws://localhost:3000/cdp/SESSION_ID?apiKey=bf_your_api_key

Rate limits

Rate limits are in-memory and configured server-side. There is no tier ladder; one host, one bucket per API key (or per IP when authless). Defaults are conservative; tune them in your deployment config if you need to.

Error responses

{ "error": "Invalid API key" }

{ "error": "Maximum concurrent sessions reached" }

Deploying to production? See the self-host guide for the full hardening checklist (TLS termination, reverse proxy, secret rotation).