Autenticação
Cada requisição à API leva uma API key do tenant como token Bearer.
O header Bearer
Inclua sua chave no header Authorization de cada chamada:
Authorization: Bearer bxk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCriar e revogar chaves
As chaves são criadas e revogadas no app, em Conta → Avançado → Chaves de API (papel admin/owner). A chave (bxk_…, 256 bits) é exibida uma única vez na criação: guarde-a em um lugar seguro. Em repouso o Bruxel guarda apenas o hash dela; se você perdê-la, revogue-a e crie outra. Cada chave tem scopes (permissões) e, opcionalmente, uma data de expiração.
Scopes
Cada chave leva um subconjunto destas permissões. Sem o scope exigido, a API responde 403.
| Scope | Permite |
|---|---|
catalog:read | Listar e ler produtos e suas descrições. |
catalog:write | Criar, atualizar e excluir produtos (upsert). |
generate | Gerar descrições (sync e em lote), cancelar lotes. |
export | Exportar o catálogo gerado em CSV. |
credits:read | Consultar o saldo de créditos. |
channels:read | Listar os canais configurados e suas colunas. |
attributes:read | Ler as definições de atributos e os valores de um produto. |
attributes:write | Escrever os valores de atributo de um produto. |
media:read | Ler as imagens de um produto e seus derivados. |
media:write | Enviar arquivos para a biblioteca (reservar cota, POST assinado para o S3 e confirmar por assinatura binária) e vinculá-los a um produto com um papel. Gasta a cota de espaço da organização. |
media:generate | Gerar imagens de produto com IA (fotos com modelo e foto principal), ler suas sessões e os modelos sintéticos. |
content:manage | Publicar, aprovar e despublicar fichas. Move o ponteiro de publicação: o que as descrições, os exports e sua loja servem. É oferecido, mas não concedido por padrão. |
events:write | Informar ao Bruxel o que aconteceu fora (SAP, o armazém, a loja) com POST /v1/events. Move o percurso dos fluxos. |
reports:read | Ler os relatórios da organização (catálogo com contagens, linhas em JSON e o CSV completo) para o seu BI. Inclui dinheiro, pessoas e o log de auditoria. |
Erros de autenticação
Uma chave inexistente, revogada ou expirada devolvem o mesmo corpo genérico de propósito (não se distingue uma da outra):
{ "detail": "api key inválida" }Um header ausente, ou que não começa com bxk_, também dá 401, com uma mensagem diferente. Detecte uma falha de auth pelo código 401, não pelo texto.