Autenticação

Toda requisição à API precisa de um token permanente, enviado no header
Authorization com o schema Bearer.

Authorization: Bearer pn_0000000000000000000000

Um token permanente autentica sua aplicação sem que você tenha que implementar
fluxo de login: cria uma vez, usa onde precisar.

Gerar o token

Na plataforma web: Ajustes → Integrações → Integração via API (Configurar) →
Novo → dê um nome ao token.

Nomeie pela plataforma que vai usá-lo — "Site institucional", "ERP",
"Automação de vendas". Você pode gerar quantos quiser, e daqui a seis meses o
nome é a única forma de saber qual token pertence a quê na hora de revogar.

O token é permanente: não expira sozinho e não precisa ser renovado a cada
chamada. Guarde-o em cofre de segredos, nunca no código-fonte nem no front-end.

Usar

curl https://api.hub.allbound.ia.br/core/v1/contact \
  -H "Authorization: Bearer pn_0000000000000000000000"

Vale para as três APIs — Core, CRM e Chat. O mesmo token atende
todas; o que muda é só o prefixo do caminho:

Sem o header, ou com token inválido, a resposta é 401:

{
  "httpStatusCode": 401,
  "error": true,
  "key": "ERROR_UNAUTHORIZED",
  "text": "Acesso negado"
}

O campo id.value dessa resposta é o identificador da requisição — é o que o
suporte pede quando você reporta um problema.

Chamadas a partir do navegador

Além do token, a API valida a origem da requisição. Chamadas de navegador
partem de uma origem (o domínio da sua página) e só passam se ela estiver
liberada. Origem não liberada recebe:

HTTP 500
Origin not allowed

Repare que é 500, não 403 — não é erro de autenticação. Token correto e
origem bloqueada dão exatamente esta resposta, o que torna fácil perder tempo
procurando problema no token.

Origin: null — o que um iframe com sandbox envia — também é recusado.

Como saber se é isso: repita a mesma chamada no Postman, no Insomnia ou em
curl. Essas ferramentas não enviam Origin, e requisições sem origem passam
normalmente. Se funciona no terminal e falha no navegador, com o mesmo token, é
a allowlist.

Para liberar um domínio novo, fale com o suporte da Allbound antes de subir
a aplicação. Vale para cada origem separadamente: ambiente de homologação,
produção e qualquer subdomínio contam como origens distintas.

📘

Chamadas de servidor não passam por isso

Backend, cron, integração server-to-server: nada disso envia Origin, então a
allowlist não se aplica. Ela só afeta código rodando dentro de um navegador.

Revogar

Na mesma tela, exclua o token. A revogação é imediata e derruba toda
integração que estivesse usando aquele token — por isso vale um por
aplicação, em vez de um compartilhado entre várias.

❗️

O token vale por toda a conta

Ele não é escopado por permissão nem por recurso: quem o tiver consegue tudo o
que a sua conta consegue, nas três APIs, sem login. Trate-o como senha: não
compartilhe com terceiros e, ao menor sinal de uso indevido, exclua e gere
outro.

Limites

As requisições são limitadas por conta: 1.000 a cada 5 minutos, mais um teto
de proteção de 200 a cada 5 segundos. Ultrapassar qualquer um devolve 429. Ver
Rate limiting.

Não confunda com a sessão do Insights

Esta página é sobre a API da plataforma — contatos, conversas, funil,
mensagens. É o que você chama de servidor, com o token pn_….

O Insights, a camada de análise embutida como menu na plataforma, o token pn_… não vale lá.