Better Data

API Reference

Authentication

Edit this page

Tenant REST API (SCM)

Programmatic access to forecasting, inventory, transfers, catalog, and alerts uses tenant-scoped credentials. The primary pattern is Bearer API keys issued from your organization’s admin settings.

API keys for SCM

API keys authenticate requests without browser sessions. Keys are tenant-scoped and support granular permissions via scopes.

Creating a key (UI)

  1. Navigate to Admin → API (/admin/api)
  2. Click Create Key
  3. Set a Name and Scopes, then create
  4. Copy the key immediately — it is shown only once

Creating a key (API)

1curl -X POST "https://app.betterdata.co/api/admin/api-keys" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Production API Key",
6    "scopes": ["inventory:read", "forecast:read"]
7  }'

Using API keys

1curl -X GET "https://app.betterdata.co/api/inventory/channel-location?locationId=loc_123&page=1&limit=50" \
2  -H "Authorization: Bearer bdk_live_ABC123_<your-key>" \
3  -H "Content-Type: application/json"

Scopes (summary)

| Area | Examples | | --- | --- | | Inventory | inventory:read, inventory:write, inventory:* | | Forecasting | forecast:read, forecast:write | | Planning / procurement / shipping / reports | planning:*, procurement:*, shipping:*, reports:read | | Admin | admin:read, admin:write (tenant admin) | | Wildcard | * — all operations (use with caution) |

Managing keys

  • List: GET /api/admin/api-keys (session auth)
  • Update: PATCH /api/admin/api-keys/{id}
  • Revoke: POST /api/admin/api-keys/{id}/revoke
  • Rotate: POST /api/admin/api-keys/{id}/rotate

API key error codes

| Code | Status | Meaning | | --- | --- | --- | | MISSING_AUTHORIZATION | 401 | No Authorization header | | INVALID_API_KEY | 401 | Key not found or invalid | | REVOKED_API_KEY | 401 | Key revoked | | EXPIRED_API_KEY | 401 | Key expired | | INACTIVE_ORGANIZATION | 403 | Org not active | | IP_RESTRICTION | 403 | Key not allowed from this IP | | INSUFFICIENT_SCOPE | 403 | Missing scope |

Store keys in environment variables or a secrets manager; rotate periodically and grant least privilege.

Commerce Gateway (LLM)

The Better Data LLM Gateway uses standard HTTP headers to verify clients.

API keys (gateway)

For server-to-server calls or a self-hosted gateway with a configured key list:

Header:

1Authorization: Bearer YOUR_API_KEY

Configure keys in LLM Gateway Configuration.

Session IDs

Include X-Session-Id to tie requests to a user’s cart and conversation history:

1X-Session-Id: unique_session_string_123

Better Data Cloud keys

When using the Hosted Gateway, use Cloud API keys from the dashboard — scoped to your account and your plan.

For handoffs from an AI to a storefront, the gateway can issue a short-lived Secure Link Token as a query parameter; the storefront upgrades it to a session cookie.

Example:

1https://mystore.com/checkout?token=st_abc123

Gateway best practices

  • Do not expose secret keys in the browser; use public keys only where appropriate for discovery
  • Keep keys in environment variables; use HTTPS (TLS 1.2+)

Webhook verification (inbound)

Inbound platform webhooks (e.g. Stripe) are verified with provider signatures — not your tenant API key. See Webhooks for Stripe and Square.