API Passo 2 - Obtendo o Bearer Token

Com as credenciais em mãos, o próximo passo é trocá-las por um access_token — a chave que acompanha todas as chamadas da API. Este artigo mostra como gerar o token, como usá-lo e o que fazer quando ele expira.

Antes de começar

• As seis credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage.
• Um usuário de serviço com perfil de administrador — o login dedicado à integração, normalmente no formato integracao + customer_id (exemplo: integracaomeucliente).
• A coleção do Postman importada, se quiser testar sem escrever código. Ela está anexada ao artigo de credenciais.

Como funciona

A autenticação tem três etapas, sempre nesta ordem:

1. Sua integração envia as credenciais para POST /auth.
2. A API devolve um access_token e o tempo de validade dele, em segundos.
3. Em todas as chamadas seguintes, o token vai no cabeçalho Authorization. Quando ele expira, a integração pede um novo.

Gerar o token no Postman

1. Selecione o Environment Engage - APIs (preencher) e confira que customerId, clientId, clientSecret, adminUser e adminPass estão preenchidos.
2. Confirme que baseUrl aponta para homologação.
3. Abra a pasta 02 - Autenticação, request Obter access_token (grant_type=password), e clique em Send.

Request de autenticação no Postman: corpo no formato x-www-form-urlencoded, com os valores vindos das variáveis do Environment

Gerar o token pelo seu sistema

1Envie as credenciais

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

grant_type=password&customer_id={customer_id}&client_id={client_id}&client_secret={client_secret}&username={username}&password={password}

2Guarde o token e a validade

Resposta de sucesso (valores ilustrativos):

{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "{refresh_token}",
  "client_id": "meusistema",
  "customer_id": "meucliente",
  "user_id": "12345",
  "device": "computer"
}

Sua integração precisa de dois campos: access_token, o token em si, e expires_in, por quantos segundos ele vale.

3Envie o token em todas as chamadas

Authorization: Bearer {access_token}

A palavra Bearer vem antes do token, separada por um espaço.

Quando o token expira

O access_token tem prazo de validade. Depois dele, qualquer endpoint passa a responder HTTP 401 — nenhum avisa antes.

• Leia sempre o expires_in da resposta. O tempo de vida é definido no cadastro de cada aplicação e muda de uma instância para outra.
• Renove com folga, antes do fim do prazo.
• Trate o 401 como "renove e tente uma vez", não como erro definitivo. Se a nova tentativa também falhar, aí sim é um problema a investigar.

Boas práticas

• Use um usuário de serviço, nunca o login de uma pessoa. Usuários comuns passam pelas políticas de troca de senha no primeiro acesso e de expiração de senha, que bloqueiam a autenticação sem aviso.
• Envie sempre o client_secret. Em algumas instâncias a chamada funciona sem ele — a integração passa em homologação e falha em produção.
• Só existem dois grant_type para integração: password, para gerar o token, e refresh_token, para renová-lo.
• Credenciais nunca vão na URL nem em log. Elas viajam no corpo da requisição.
• Evite repetição automática em loop. Muitas tentativas com senha errada travam o usuário por alguns minutos.

Problemas comuns

A pasta 98 - Erros comuns da coleção traz o catálogo completo de erros e uma chamada de diagnóstico que separa "o token expirou" de "falta permissão".