Passo 2.1 — access_token, refresh_token e customer_token: qual é qual

A API da Engage usa três tokens com nomes parecidos — e trocar um pelo outro é a causa mais comum de erro 401 no primeiro dia de integração. Este artigo explica o papel de cada um, como renovar o acesso sem repetir o login e por que um login pode derrubar outro.

Antes de começar

• Gere seu primeiro token seguindo Passo 2 — Obtendo o access_token (POST /auth).
• As credenciais usadas aqui são as mesmas, reunidas em Comece por aqui: credenciais para integrar com a API da Engage.
• Teste em homologação (https://sandbox.engage.bz/api/v1) antes de apontar para produção.

Os três tokens

Renovar o acesso

Há duas formas de manter a integração autenticada. Escolha conforme a resposta do seu login.

Forma 1 — Repetir o login. Quando o token expira, faça de novo o POST /auth com grant_type=password. É o cenário mais comum em integração servidor a servidor, e é perfeitamente aceitável: uma rotina que roda de hora em hora pode simplesmente autenticar a cada execução.

Forma 2 — Usar o refresh_token. Só está disponível se a resposta do login trouxer um refresh_token — isso depende de como a aplicação foi registrada. Serve para quem precisa manter a sessão viva sem guardar a senha.

1Envie o refresh_token

POST https://sandbox.engage.bz/api/v1/auth
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token={refresh_token}&customer_id={customer_id}&client_id={client_id}

2Guarde o novo refresh_token

A resposta tem o mesmo formato do login: um novo access_token, o expires_in e um novo refresh_token.

Saber se o token ainda vale

Para conferir sem fazer uma chamada de negócio:

GET https://sandbox.engage.bz/api/v1/{customer_id}/login/authenticated
Authorization: Bearer {access_token}

A resposta é 200 quando o token é válido e 401 quando não é. Útil para separar "o token expirou" de outros problemas.

Por que um login derruba outro

Gerar um token novo derruba o anterior. A regra vale para a mesma combinação de usuário, instância, client_id e device: dois processos seus autenticando com o mesmo usuário e o mesmo device vão se derrubar em rodízio.

O customer_token em detalhe

Ele é obtido sem autenticação:

GET https://sandbox.engage.bz/api/v1/{customer_id}/infos/token

{
  "result": {
    "customer_id": "meucliente",
    "name": "Meu Cliente",
    "status": true,
    "token": "{customer_token}",
    "platform_url": "https://meucliente.engage.bz"
  }
}

O campo token é o customer_token: 32 caracteres que não mudam. Obtenha uma vez e guarde junto da configuração da sua integração.

• HTTP 200 com {"result": null} não é sucesso. É a resposta quando o customer_id não existe ou a instância está inativa. Trate esse caso e nunca grave null como customer_token.
• Continue enviando ?customerToken= nos endpoints que o pedem, como os de usuários e grupos. É o contrato publicado da API.
• O customer_token não é um segredo forte. Ele identifica a instância, é devolvido por um endpoint público e, por ir na URL, aparece em logs de servidor e de proxy. Trate com higiene — não versione, não registre em log —, mas não construa controle de acesso em cima dele.

No Postman

A pasta 02 - Autenticação traz uma chamada para cada situação deste artigo:

Resposta do request Obter customer_token da instância. O valor do token está oculto.

Problemas comuns

A pasta 98 - Erros comuns da coleção reúne o catálogo completo de erros da API e três chamadas de diagnóstico.