Getting Started

Authentication

All API requests require authentication via an API key. Self-hosted instances can optionally run without authentication.

API Key Format

API keys are prefixed with bf_ followed by 32 hexadecimal characters. Keys are generated when you sign up or when a Stripe subscription is created via the webhook.

text

bf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Header Authentication

Pass your API key in the x-api-key header on every REST API request.

curl https://api.browsefleet.com/v1/sessions \
  -H "x-api-key: bf_your_api_key"

WebSocket Authentication

For CDP WebSocket connections, pass your API key as a query parameter. The session ID is part of the URL path.

text

ws://api.browsefleet.com/cdp/SESSION_ID?apiKey=bf_your_api_key

When connecting with Puppeteer or Playwright, use the websocketUrl returned by the create session endpoint. The URL already includes the correct path.

Rate Limits

Rate limits vary by tier. Exceeding limits returns HTTP 429 with a JSON error body.

Tier	Concurrent Sessions	Daily Requests
Hobby	5	500
Starter	10	1,000
Developer	20	Unlimited
Pro	100	Unlimited

Error Responses

401 Unauthorized

Returned when the API key is missing, invalid, or deactivated.

json

{ "error": "Invalid API key" }

429 Too Many Requests

Returned when you exceed concurrent session limits or daily request quotas.

json

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

Self-Hosted Authentication

For self-hosted instances, set the API_KEYS environment variable to a comma-separated list of valid keys. If left empty, authentication is disabled and all requests are allowed.

bash

# Enable authentication with two keys
API_KEYS=bf_key_one,bf_key_two

# Disable authentication (open access)
API_KEYS=