Skip to main content
Uma API key é um segredo do workspace enviado como header HTTP. Cada key tem um nome e as permissões (scopes) que você escolher, e um workspace pode ter quantas precisar — o normal é uma por integração, para poder revogar só ela.
O formato é wbx_key_ seguido de 48 caracteres hexadecimais. As keys servem para duas coisas:
  • Account API (/account/*): é a única credencial. Cada rota pede uma permissão.
  • Rotas de instância (/instances/{instance_id}/token/{token}/*): camada opcional por cima do token da URL, ligada em Exigir API key nas rotas de instância.
O token da instância na URL não muda: ele continua sendo a credencial base das rotas de instância e, por padrão, nenhum header é necessário nelas.

​
Permissões

Marque só o que a integração precisa. Um backend que apenas envia mensagens precisa de instances:operate (e só se a exigência estiver ligada); um provisionador de instâncias precisa de instances:read e instances:write. As permissões da Account API só funcionam em contas com plano.

​
Como criar

1

Crie a key

No painel, em Segurança › API keys, clique em Nova API key. Dê um nome que identifique a integração (ex.: “Backend de produção”) e marque as permissões. Owners e admins criam, editam e revogam; membros só veem a lista.
2

Copie o valor

A key aparece uma única vez, na criação. Só o hash fica guardado: copie para o seu cofre de segredos. Perdeu? Revogue e crie outra.
3

Envie no header

Authorization: Bearer wbx_key_… em toda chamada que precisa da key.
A lista mostra, para cada key, uma dica do valor (wbx_key_3f9a…c2e1), as permissões e o último uso. Dá para editar as permissões de uma key existente sem trocar o valor dela.

​
Exigir API key nas rotas de instância

O token da instância vai na URL, e URLs vazam com facilidade: logs de proxy, histórico de navegador, planilhas, capturas de tela. Com a exigência ligada, toda requisição a qualquer instância do workspace precisa trazer, além do token na URL, uma key com instances:operate em um header, que raramente é registrado. Se uma URL vazar, quem a tiver ainda não consegue usar a API.
1

Crie uma key com instances:operate

O painel só deixa ligar a exigência se existir pelo menos uma key com essa permissão.
2

Configure suas integrações

Adicione o header Authorization: Bearer wbx_key_… em todas as chamadas, de todas as instâncias do workspace. Teste com GET /status — com a exigência desligada o header é ignorado, então dá para preparar tudo antes.
3

Ative a exigência

Ligue Exigir API key nas rotas de instância. A partir daí, requisições sem o header (ou com uma key inválida) recebem 401 api_key_required, e com uma key sem instances:operate, 403 insufficient_scope.
A exigência vale para todas as instâncias do workspace ao mesmo tempo, inclusive as usadas por ferramentas no-code. Atualize tudo antes de ligar.
Enquanto a exigência está ligada, a última key com instances:operate não pode ser revogada nem perder essa permissão: o painel recusa. Desligue a exigência antes, ou crie outra key com a permissão. No MCP, a exigência não se aplica a apps autorizados por OAuth. Com o token da instância como bearer ela vale, e a key vai no header Client-Token (o Authorization já está ocupado pelo token da instância).

​
Alias Client-Token

Para quem vem da z-api: nas rotas de instância, a key também pode ir no header Client-Token em vez de Authorization: Bearer, com o mesmo valor. Quem já envia Client-Token só troca o valor pelo de uma API key do Wabox com instances:operate.
  • O nome do header não diferencia maiúsculas (client-token também funciona).
  • O alias vale nas rotas de instância e no /mcp com o token da instância como bearer. A Account API (/account/*) aceita só Authorization: Bearer.
  • Client-Tokens gerados antes das API keys foram migrados automaticamente para uma key chamada “Client-Token (migrado)”, com instances:operate. O valor antigo continua funcionando no header Client-Token, e o estado da exigência (ligada ou desligada) foi mantido. Nada precisa mudar nas integrações existentes; quando quiser, crie keys novas por integração e revogue a migrada.

​
Rotação sem downtime

Revogar uma key é imediato e não afeta as outras. Como várias keys convivem, a troca não tem janela de indisponibilidade:
  1. Crie uma key nova com as mesmas permissões.
  2. Atualize a integração para usar a nova e confirme que está funcionando. O último uso na lista ajuda a ver se a antiga ainda recebe chamadas.
  3. Revogue a antiga.
Veja também Rotação de token e segredo.

​
Erros