Autenticação e tokens

A API pública é autenticada por tokens de acesso pessoal (PAT). Um único token está vinculado à conta e age sobre todas as suas entidades do construtor dentro dos escopos concedidos.

Criando um token

O token pessoal é criado no painel pessoal, na seção de tokens pessoais. O valor do token é exibido uma única vez no momento da criação — salve-o em local seguro. No servidor, o token é armazenado apenas em forma de hash e não pode ser recuperado; se perdido, emita um novo e exclua o antigo.

Todos os tokens pessoais começam com o prefixo mbp_.

Transmitindo o token

O token deve ser enviado em cada requisição HTTP no cabeçalho Authorization usando o esquema Bearer:

Authorization: Bearer mbp_SEU_TOKEN

O mesmo cabeçalho é usado para acesso de sessão no painel web (onde é um JWT de curta duração), mas para integrações use o token pessoal mbp_….

Escopos de acesso

O token possui um conjunto de escopos no formato recurso:ação. Leitura requer sufixo :read, alterações requerem :write. Escopos disponíveis:

  • bots:read, bots:write — bots, suas configurações, sincronização, token do bot.
  • reactions:read, reactions:write — reações, importação, teste de fórmulas, vínculos, ordem.
  • labels:read, labels:write — marcações de assinantes.
  • collections:read, collections:write — coleções e registros.
  • flows:read, flows:write — fluxos.
  • integrations:read, integrations:write — integrações, conexões, credenciais.
  • media:write — upload para a biblioteca de mídia.
  • templates:read, templates:write — templates de bots.
  • settings:read, settings:write — configurações.
  • subscribers:read — assinantes e histórico de diálogo (somente leitura).
  • broadcasts:write — transmissões e seu gerenciamento.
  • stats:read — estatísticas e análises.
  • billing:read — saldo e planos (somente leitura).

O escopo especial * concede acesso total ao conjunto público de endpoints.

O que está acessível pelo token e o que não está

Com token pessoal só são acessíveis endpoints do construtor — os que "ajudam a construir o bot". Não acessíveis via PAT (somente por sessão web): login e registro, endpoints mobile, pagamento e recarga de saldo, notificações, journal de auditoria, envio de mensagens no diálogo pelo operador, webhooks de entrada e callbacks de pagamento, WebSocket. Uma requisição com token mbp_ a essa rota retornará 401 ou 403.

Se o token não tiver o escopo necessário para uma rota específica, será retornado 403. Mais detalhes sobre os códigos em guia de erros.

Próximos passos