Authentification
Chaque requête à l'API porte une clé API du tenant comme jeton Bearer.
L'en-tête Bearer
Incluez votre clé dans l'en-tête Authorization de chaque appel :
Authorization: Bearer bxk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCréer et révoquer des clés
Les clés se créent et se révoquent dans l'app, sous Compte → Avancé → Clés API (rôle admin/owner). La clé (bxk_…, 256 bits) ne s'affiche qu'une seule fois à la création : conservez-la en lieu sûr. Au repos, Bruxel ne garde que son hash ; si vous la perdez, révoquez-la et créez-en une autre. Chaque clé a des scopes (permissions) et, en option, une date d'expiration.
Scopes
Chaque clé porte un sous-ensemble de ces permissions. Sans le scope requis, l'API renvoie 403.
| Scope | Permet |
|---|---|
catalog:read | Lister et lire les produits et leurs descriptions. |
catalog:write | Créer, mettre à jour et supprimer des produits (upsert). |
generate | Générer des descriptions (sync et par lot), annuler des lots. |
export | Exporter le catalogue généré en CSV. |
credits:read | Consulter le solde de crédits. |
channels:read | Lister les canaux configurés et leurs colonnes. |
attributes:read | Lire les définitions d'attributs et les valeurs d'un produit. |
attributes:write | Écrire les valeurs d'attribut d'un produit. |
media:read | Lire les images d'un produit et leurs dérivés. |
media:write | Envoyer des fichiers dans la bibliothèque (réserver le quota, POST signé vers S3 et confirmation par signature binaire) et les lier à un produit avec un rôle. Consomme le quota d'espace de l'organisation. |
media:generate | Générer des images produit par IA (photos avec mannequin et photo principale), lire leurs sessions et les mannequins synthétiques. |
content:manage | Publier, approuver et dépublier des fiches. Déplace le pointeur de publication : ce que servent les descriptions, les exports et votre boutique. Proposé mais non accordé par défaut. |
events:write | Signaler à Bruxel ce qui s’est passé à l’extérieur (SAP, l’entrepôt, la boutique) avec POST /v1/events. Fait avancer le parcours des flux. |
reports:read | Lire les rapports de l’organisation (catalogue avec comptes, lignes en JSON et le CSV complet) pour votre BI. Inclut l’argent, les personnes et le journal d’audit. |
Erreurs d'authentification
Une clé inexistante, révoquée ou expirée renvoient le même corps générique à dessein (on ne les distingue pas) :
{ "detail": "api key inválida" }Un en-tête absent, ou qui ne commence pas par bxk_, renvoie aussi 401, avec un message différent. Détectez un échec d'auth par le code 401, pas par le texte.