Skip to main content

Authentication

:::info What you'll learn By the end of this page you will understand:

  • How to authenticate requests with the X-API-Key header
  • How to request an API key
  • IP whitelisting, origin restrictions, and HTTPS requirements
  • Security best practices for storing and rotating keys :::

Every request to the Booking Brain Developer API must include an API key. This page explains how keys work, how to get one, and how to keep your integration secure.

How it works​

Pass your API key in the X-API-Key header on every request:

curl "https://app.bookingbrain.com/api/v1/developer/search?property_place_slug=stay-in-exmoor" \
  -H "X-API-Key: YOUR_API_KEY"
const response = await fetch(
  "https://app.bookingbrain.com/api/v1/developer/search?property_place_slug=stay-in-exmoor",
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
    },
  }
);
import requests

response = requests.get(
    "https://app.bookingbrain.com/api/v1/developer/search",
    params={"property_place_slug": "stay-in-exmoor"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

:::caution Important Do not use Authorization: Bearer or any other authentication scheme. The API exclusively uses the X-API-Key header. :::

Getting an API key​

API keys are issued per-client by the Booking Brain team. There is no public sandbox key -- every key is registered to a named client and unlocks the full API, including real booking creation and payment processing.

Capability
All read endpointsYes
Create bookingsYes -- creates real bookings
Process paymentsYes -- charges real cards via SagePay/Opayo
IP whitelistingConfigured per key
Origin restrictionsOptional (configured per key)
Rate limitPer-minute, configurable per client

:::caution Live environment All keys operate against live data. Booking and payment endpoints create real bookings and charge real cards -- when testing, stick to the read-only endpoints (search, property details, availability, pricing) unless you have agreed a test procedure with the Booking Brain team. :::

To request a key, contact support@bookingbrain.co.uk with:

  1. Your company name and website
  2. A description of your integration
  3. The IP addresses that will make API calls
  4. The origin domains for browser-based requests (if applicable)

HTTPS required​

All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected. This ensures your API key and all request/response data are encrypted in transit.

Base URL​

All API requests use a single base URL:

https://app.bookingbrain.com/api/v1/developer

IP whitelisting​

API keys can be locked to specific IP addresses. Requests from non-whitelisted IPs will receive a 403 Forbidden response:

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}

To update your whitelisted IPs, contact Booking Brain support. You can register multiple IPs per key (for example, your production servers, staging environment, and CI/CD runners).

Origin restrictions​

For browser-based integrations (JavaScript running on your website), keys can optionally be restricted to specific origins. This prevents your key from being used on unauthorised domains.

When configured, the API checks the Origin header against the allowed list. Requests from non-matching origins receive a 403 Forbidden response.

Authentication errors​

If authentication fails, you will receive one of these responses:

Missing API key​

HTTP/1.1 403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}

Cause: The X-API-Key header is missing from the request.

Invalid API key​

HTTP/1.1 403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}

Cause: The API key does not match any active key in the system.

IP not whitelisted​

HTTP/1.1 403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}

Cause: The request is coming from an IP address that is not on the key's whitelist.

Origin not allowed​

HTTP/1.1 403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}

Cause: The Origin header does not match the key's allowed origins. This only applies to keys with origin restrictions configured.

:::tip Debugging 403 errors All 403 responses look the same for security reasons -- the API does not reveal which specific check failed. If you are getting unexpected 403 errors:

  1. Verify the key is correct (no trailing whitespace or newline characters)
  2. Check the IP address your server is using (it may differ from your local machine)
  3. Confirm your IPs are whitelisted with Booking Brain support
  4. For browser requests, check the Origin header matches your allowed domains :::

Security best practices​

Never expose API keys in client-side code​

If your website calls the API directly from the browser, the API key is visible in network requests. This is only acceptable for keys with origin restrictions configured, but for maximum security:

  • Server-side proxy (recommended): Make API calls from your backend server and return results to the frontend. Your API key stays on the server and is never exposed.
  • Origin restrictions: If you must call the API from the browser, ensure your key has origin restrictions configured.

Rotate keys if compromised​

If you suspect a key has been compromised, contact Booking Brain support immediately to revoke it and issue a replacement.

Use environment variables​

Store your API key in an environment variable, not in source code:

# .env (never commit this file)
BOOKINGBRAIN_API_KEY=bb_prod_your_key_here
// Read from environment
const API_KEY = process.env.BOOKINGBRAIN_API_KEY;
import os

API_KEY = os.environ["BOOKINGBRAIN_API_KEY"]

One key per environment​

Use separate keys for development, staging, and production. This makes it easy to revoke a compromised key without disrupting other environments.

Next steps​