Authentication
Every API request carries a tenant API key as a Bearer token.
The Bearer header
Include your key in the Authorization header of every call:
Authorization: Bearer bxk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCreating and revoking keys
Keys are created and revoked in the app, under Account → Advanced → API Keys (admin/owner role). The key (bxk_…, 256 bits) is shown only once at creation — store it somewhere safe. At rest Bruxel keeps only its hash; if you lose it, revoke it and create another. Each key has scopes (permissions) and, optionally, an expiration date.
Scopes
Each key carries a subset of these permissions. Without the required scope, the API returns 403.
| Scope | Allows |
|---|---|
catalog:read | List and read products and their descriptions. |
catalog:write | Create, update and delete products (upsert). |
generate | Generate descriptions (sync and batch), cancel batches. |
export | Export the generated catalog to CSV. |
credits:read | Check the credit balance. |
channels:read | List the configured channels and their columns. |
attributes:read | Read attribute definitions and a product's values. |
attributes:write | Write a product's attribute values. |
media:read | Read a product's images and their derivatives. |
media:write | Upload files to the library (reserve quota, signed POST to S3 and confirm by binary signature) and link them to a product with a role. It spends the organization's storage quota. |
media:generate | Generate product images with AI (model photos and main photo), read their sessions and the synthetic models. |
content:manage | Publish, approve and unpublish listings. Moves the publication pointer: what descriptions, exports and your store serve. Offered but not granted by default. |
events:write | Report to Bruxel what happened outside (SAP, the warehouse, the store) with POST /v1/events. It moves flow journeys. |
reports:read | Read the organization's reports (catalog with counts, rows as JSON and the full CSV) for your BI. Includes money, people and the audit log. |
Authentication errors
A nonexistent, revoked or expired key all return the same generic body on purpose (you can't tell them apart):
{ "detail": "api key inválida" }A missing header, or one that doesn't start with bxk_, also returns 401, with a different message. Detect an auth failure by the 401 code, not by the text.