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.
O ponto mais importante: é um token por pessoa
Seção intitulada “O ponto mais importante: é um token por pessoa”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.
Pegar o token
Seção intitulada “Pegar o token”- Avatar, no canto superior direito → Perfil
- Role até Token de acesso
- Copiar
Ele fica visível sempre — não é daqueles que aparecem uma vez só.
GET /api/v1/accounts/1/conversationsHost: app.smart2.com.brapi_access_token: SEU_TOKENContent-Type: application/jsoncurl "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.
Trocar o token
Seção intitulada “Trocar o token”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 token pode fazer
Seção intitulada “O que o token pode fazer”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.
Erros de autenticação
Seção intitulada “Erros de autenticação”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.
404 que na verdade é permissão
Seção intitulada “404 que na verdade é permissão”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.
Segurança
Seção intitulada “Segurança”Nunca no navegador
Seção intitulada “Nunca no navegador”<!-- 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.
Em variável de ambiente, nunca no código
Seção intitulada “Em variável de ambiente, nunca no código”import osSMART_TOKEN = os.environ["SMART_TOKEN"]Se commitou no Git
Seção intitulada “Se commitou no Git”- Reinicie o token no painel, primeiro — antes de qualquer outra coisa
- Atualize as variáveis de ambiente das integrações
- Limpar o histórico do Git depois é higiene, não conserto: o valor já saiu do seu controle
Rotação
Seção intitulada “Rotação”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.
Dúvidas comuns
Seção intitulada “Dúvidas comuns”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.
Próximos passos
Seção intitulada “Próximos passos”- Quickstart — a primeira requisição
- Convenções — paginação, erros, filtros
- CORS — por que não dá para chamar do navegador
- Limites