Authentication

The Authorization header

POST /bigblue.storeapi.v1.PublicAPI/ListOrders HTTP/1.1
Host: api.bigblue.co
Authorization: Bearer <api_key>
Content-Type: application/json

{}

This is the only supported method. Query-string keys, basic auth and OAuth aren't supported.

Creating keys

Create keys in the Bigblue app by creating an integration. Each key belongs to an integration, and the API reads these integration settings on every request:

Primary warehouse: Warehouse ID
Default warehouse for auto-fulfilled orders. Override it per order with auto_fulfill_warehouse.
Auto-fulfill orders: On or off
Whether orders created with this key go to the warehouse automatically. You can't set this per request.
Display name: Text
Shown in the app so you can tell integrations apart.

Two keys on the same account can therefore handle the same CreateOrder request differently. If auto-fulfillment is off, the auto_fulfill_* fields on the order are ignored.

Use one key per system

Create a separate integration for each system that calls Bigblue. Orders record the integration that created them, and ListOrders with via_api: true returns only the calling key's orders.

Scope

A key gives access to one Bigblue account and one integration. You can only read and write that account's data.

Your account has a four-character tenant code. Product, bundle, order and return IDs start with it: an account with the tenant BGBL has products such as BGBL-ESPSRT-SMAL and bundles such as BGBLBU-KITSTA-2024. See Identifiers.

Rotating keys

You can have several active keys, so you can rotate without downtime:

Create a new integration and copy its key.

Deploy the new key. Copy the warehouse and auto-fulfill settings from the old integration.

When traffic uses the new key, revoke the old one in the app.

Requests with a revoked key fail with permission_denied. Data created with that key isn't affected.

Errors

401The Authorization header is missing or doesn't start with Bearer.

{ "code": "unauthenticated", "msg": "api key must be included" }

Check that the header is named Authorization and that the value starts with Bearer followed by a space.

403The key isn't recognized, is malformed or has been revoked.

{ "code": "permission_denied", "msg": "unauthorized" }

The response is the same in all three cases. Check that you copied the whole key.

403 is also used for rate limiting

A 403 with the code resource_exhausted means you exceeded the rate limit. Check the code field, not only the HTTP status. See Rate limits.

Storing keys

Keep keys on your server, in a secret manager. Never put them in browser code, mobile apps or public repositories.
Bigblue logs each request with its integration, method and payload. You can review activity per key in the app.
There is no sandbox or test key. Test with read-only requests first, and delete any test products you create.

Webhooks use a different secret

Webhook requests come from Bigblue to you and don't use your API key. Bigblue signs them with your account's shared secret. See Verify signatures.