Authentication

API keys

Each business has one API key. Your business's Primary Admin manages it from the Orbita dashboard under Settings → API Keys, confirming their password for every change:

• Generate a key. It is shown once, in the form <appId>.<secret> — store it in a secret manager straight away.
• Rotate the key. A new key is issued and the old one stops working.
• Revoke the key to switch off API access for your business.

Send the key in the x-api-key header on every request:

curl "{baseUrl}/api/rates" \
  -H "x-api-key: <appId>.<secret>" \
  -H "X-Signature: <signature>" \
  -H "X-Signature-Timestamp: <unix ms>"

IP allowlist

Requests are accepted only from IP addresses on your business's allowlist. Bluebulb manages the list for you — send the public IP addresses of the servers that call the API to your Bluebulb contact, and tell them before those addresses change.

• Addresses are matched exactly; ranges (CIDR) aren't supported, so list each address.
• If your allowlist is empty, every request is rejected.
• A request from an unlisted address gets 403 with the address Orbita saw, which helps when your traffic leaves through a proxy or NAT gateway.

Request signing

Every request also carries an RSA-SHA256 signature in the X-Signature and X-Signature-Timestamp headers, made with a private key only you hold. This proves the request came from you and wasn't altered or replayed. Setup and code are on Request signing.

Rate limits

Each API key can make 60 requests per minute to each endpoint. Going over returns 429; wait a few seconds and retry with backoff. Poll status endpoints at a sensible interval (e.g. every 30–60 seconds) rather than in a tight loop.

Authentication errors

These can be returned by any authenticated endpoint: