Pular para o conteúdo

Autenticação

A API usa token de acesso em header HTTP. Não há OAuth, JWT nem chave com segredo — é um valor único que autentica como aquele usuário.

Cada usuário tem exatamente um token de acesso. Não é possível criar um segundo, nem dar nome, nem definir escopo, nem prazo de validade.

  1. Avatar, no canto superior direito → Perfil
  2. Role até Token de acesso
  3. Copiar

Ele fica visível sempre — não é daqueles que aparecem uma vez só.

GET /api/v1/accounts/1/conversations
Host: app.smart2.com.br
api_access_token: SEU_TOKEN
Content-Type: application/json
Terminal window
curl "https://app.smart2.com.br/api/v1/accounts/1/conversations" \
-H "api_access_token: SEU_TOKEN"

Na URL como parâmetro não funciona — só no header. É de propósito: token em URL fica gravado em log de servidor e em histórico de navegador.

No mesmo lugar, o botão Reiniciar gera um token novo. Peça confirmação duas vezes porque é o que é: o token antigo morre no ato, e toda integração que usava ele para de funcionar até você atualizar.

É o que fazer quando o token vaza — não existe “revogar um” porque não existe mais de um.

O que o usuário dono dele pode fazer. Não há escopo separado: um token de administrador é um token de administrador, mesmo que a integração só precise ler contatos.

Daí a recomendação do começo: o usuário da integração recebe o papel mais restrito que resolva o problema. Veja papéis e permissões.

Token ausente, errado ou já redefinido.

O caso mais comum é bobo: espaço ou quebra de linha colados junto com o token. Se você leu de arquivo ou variável de ambiente, tire as pontas:

TOKEN = os.environ["SMART_TOKEN"].strip()

Token válido, usuário sem permissão para aquela ação. A resposta vem assim:

{ "error": "You are not authorized to do this action" }

Ajuste o papel do usuário da integração, ou revise o que ela está tentando fazer.

Pedir um recurso de outra conta devolve 404, não 403. Se você tem certeza de que o id existe e mesmo assim recebe “não encontrado”, confira o account_id da URL.

<!-- errado -->
<script>
fetch('/api/v1/accounts/1/conversations', {
headers: { api_access_token: 'TOKEN' }
})
</script>

Quem abrir o inspetor vê o token e passa a ter o acesso inteiro daquele usuário. Além disso a chamada nem funciona: a API não aceita chamada de navegador de outro domínio. Veja CORS.

O caminho é o seu servidor guardar o token e expor ao seu front só o que ele precisa.

import os
SMART_TOKEN = os.environ["SMART_TOKEN"]
  1. Reinicie o token no painel, primeiro — antes de qualquer outra coisa
  2. Atualize as variáveis de ambiente das integrações
  3. Limpar o histórico do Git depois é higiene, não conserto: o valor já saiu do seu controle

Como não dá para ter dois tokens ao mesmo tempo, a troca tem um instante de parada. Programe: reinicie o token e atualize a variável de ambiente na sequência, fora do horário de pico.

Posso gerar token pela API? Não. Só pelo painel.

O token expira? Não. Vale até você reiniciar.

Posso ter um token só de leitura? Não pelo token. A restrição vem do papel do usuário — crie o usuário da integração com um papel que só leia.

Dá para compartilhar um token entre sistemas? Dá, e é justamente o que causa problema: um vazamento derruba todos juntos. Um usuário por integração.

O token funciona em todos os endpoints? Nos que o usuário dele tem permissão de usar.

Como sei qual integração fez o quê? Pelo usuário. É mais um motivo para cada integração ter o seu: no histórico da conversa aparece o nome, não um token anônimo.