Autenticação e apps na API da HubSpot: os fundamentos que evitam dor depois

Tem uma verdade que quase todo desenvolvedor de integração aprende do jeito difícil: a maior parte dos problemas que aparecem lá na frente nasce de uma decisão tomada lá no começo, na autenticação. O token errado, o escopo a mais, o segredo no lugar errado. Essas escolhas parecem detalhes na primeira semana e viram pesadelo no primeiro incidente.

Por isso vale a pena gastar trinta minutos entendendo bem a autenticação da API da HubSpot antes de escrever a primeira chamada. É o investimento de melhor retorno de toda a integração. Acertar aqui te poupa do 403 por escopo, do token vazado em um log e da dor de revogar uma credencial que está espalhada por seis integrações diferentes. Neste guia, vou cobrir os fundamentos que sustentam tudo: os tipos de credencial, os escopos, os tokens e a segurança que não pode faltar.

A primeira decisão: qual credencial usar

A HubSpot tem mais de um jeito de autenticar hoje, e escolher o certo no começo evita retrabalho pesado depois. A escolha se resume a duas perguntas: quantos portais vão usar a integração e de quais recursos ela precisa. As antigas API Keys (hapikey) foram descontinuadas em 2022, então não são mais uma opção. As credenciais que você de fato escolhe são estas.

• App privado (token estático): serve a um único portal. Você o cria nas configurações daquele portal, ele recebe um token fixo, e esse token define exatamente qual portal será afetado. É o caminho mais simples para integrações internas e é totalmente suportado.
• Account service keys (beta): uma chave estática com escopo para chamadas REST diretas, gerida em Development, Keys. Rápida de configurar, mas não autentica webhooks nem UI extensions.
• Apps OAuth: para aplicações que vários portais diferentes vão instalar, com um fluxo de consentimento e tokens de acesso que se renovam ao longo do tempo.
• Apps do novo developer platform (feitos com a CLI da HubSpot): configuração como código, autenticados por token estático ou OAuth. É o que você precisa quando a integração exige webhooks, app cards, custom workflow actions ou serverless.

A regra de bolso: um único portal chamando só REST, um app privado ou uma service key; muitos portais, um app OAuth; qualquer coisa que precise de webhooks ou outras features de app, um app no novo platform. Errar essa escolha custa caro, porque começar com app privado e depois precisar distribuir para vários portais significa reescrever toda a camada de autenticação. Por isso, antes de qualquer linha de código, responda com honestidade: quantos portais essa integração vai atender e de quais recursos ela precisa?

Escopos: o princípio do menor privilégio na prática

Cada token recebe escopos, que são permissões organizadas por área e por ação. O escopo crm.objects.contacts.read libera ler contatos, e o crm.objects.contacts.write libera escrevê-los. Há escopos próprios para empresas, negócios, automação, formulários e por aí vai. O princípio que deve guiar a escolha é o do menor privilégio: conceda ao token apenas os escopos que a tarefa específica dele exige, e nada além. Um token cuja função é extrair dados para relatórios ou um data warehouse deveria ter só escopos de leitura, jamais de escrita. Essa disciplina não é burocracia, é a sua principal rede de segurança, porque limita o estrago caso o token caia em mãos erradas.

Por que separar leitura de escrita importa

Misturar leitura e escrita num único token para facilitar é um erro comum que cobra o preço depois. Um token de leitura que vaza permite que alguém veja seus dados, o que já é ruim. Um token que também tem escrita permite que alguém altere ou apague seus registros, o que é catastrófico. Separar as funções em tokens diferentes, com escopos mínimos em cada, transforma um incidente grave em um incidente gerenciável. E, de quebra, facilita auditar quem fez o quê, porque cada token conta uma história clara sobre o que ele pode e não pode fazer.

Como enviar o token em cada chamada

Seja app privado, service key ou OAuth, o token viaja no cabeçalho de autorização, como Bearer, em toda requisição. A base de todas as chamadas é a mesma, e o portal afetado é definido pelo token, não pela URL, o que reforça por que o token é o item mais sensível de toda a operação.

Em apps OAuth, há uma camada a mais. O token de acesso tem vida curta e precisa ser renovado periodicamente usando o refresh token. Trate essa renovação como parte integrante da integração, não como um detalhe. Uma integração OAuth que não cuida bem da renovação simplesmente para de funcionar quando o token de acesso expira, geralmente no pior momento. Credenciais estáticas, um token de app privado ou uma service key, não expiram sozinhas, mas ainda assim você deve girá-las periodicamente.

Rate limits e versionamento entram na conta cedo

Autenticar é o primeiro passo, mas dois fatores adjacentes precisam estar no seu radar desde o desenho. O primeiro são os limites de taxa: cada portal tem um teto diário e um de rajada, que variam por assinatura, e a Search API tem um limite próprio e mais baixo. O segundo é o versionamento: desde março de 2026, a HubSpot usa versionamento por data, com URLs no formato /2026-03/ e breaking changes só duas vezes por ano, em março e setembro. Os caminhos legados de v1 a v4 ainda funcionam, mas o v4 fica sem suporte em 30 de março de 2027, então fixe uma versão e acompanhe o changelog. Pensar nesses dois fatores desde o começo é mais barato do que descobri-los em produção.

Segurança do token, sem exceção

O token dá acesso direto ao portal, então tratá-lo como o segredo mais valioso da operação é a prioridade número um. As práticas abaixo não são opcionais, são o mínimo que separa uma integração responsável de um incidente esperando para acontecer.

• Guarde em cofre de credenciais. Token só em cofre: o Vault do Postman, o gerenciador do n8n ou do Make, variáveis de ambiente protegidas. Nunca no corpo de uma coleção, em uma URL, em um log ou em um repositório de código.
• Um token por integração. Isso permite revogar um sem derrubar os outros e facilita auditar a origem de cada ação.
• Rotação e revogação. Gire os tokens periodicamente e revogue na hora quando alguém sai do time ou quando há qualquer suspeita de vazamento. As account service keys têm cadência de rotação recomendada de cerca de seis meses.
• Somente HTTPS. Todas as chamadas usam a base segura. Nunca chame por um canal sem criptografia.
• Minimização de dados. Extraia apenas as propriedades que a tarefa exige, para não trafegar dados pessoais sem necessidade.
• A HubSpot desativa tokens expostos. Desde outubro de 2024, a HubSpot desativa automaticamente tokens que encontra expostos publicamente, por exemplo em um repositório do GitHub, e avisa a conta. Trate isso como uma rede de segurança de último recurso, não como motivo para relaxar.

Por que isso importa para a sua operação

Autenticação parece um assunto puramente técnico, daqueles que só interessam a quem escreve o código. Não é. A forma como você autentica define o risco que a operação inteira corre. Um token com escopos largos demais, guardado no lugar errado, é uma porta aberta para o seu CRM, que costuma guardar os dados mais sensíveis da empresa: contatos, negócios, histórico de clientes. Se esse token vaza, o estrago não é um bug, é um incidente de segurança e, dependendo dos dados, uma questão de conformidade com a LGPD.

Pensar a autenticação com cuidado é, no fundo, proteger o ativo mais valioso da operação de receita: a base de relacionamento com os clientes. Não é exagero técnico, é responsabilidade com o negócio. Uma integração que começa com autenticação bem desenhada raramente vira manchete interna por um vazamento. Uma que começa relaxada nesse ponto é só uma questão de tempo.

Erros comuns que cobram o preço depois

Alguns hábitos parecem atalhos inocentes no começo e viram problema sério mais tarde. O mais comum é a credencial única para tudo, usada por várias integrações ao mesmo tempo, o que torna impossível revogar uma sem arriscar derrubar as outras. Outro é colar o token direto no fluxo de automação ou no código, em vez de referenciá-lo de um cofre, deixando o segredo exposto para qualquer um que tenha acesso ao fluxo. Um terceiro é nunca girar os tokens, deixando uma credencial viva por anos, muito depois de as pessoas que a criaram terem saído.

Evitar esses erros não exige nada sofisticado, só disciplina desde o primeiro dia. Um token por integração, escopos mínimos, segredo no cofre e rotação periódica. São quatro hábitos simples que transformam a autenticação de um ponto frágil em uma base sólida sobre a qual o resto da integração pode crescer com tranquilidade.

Na prática: a credencial que estava em todo lugar

Uma operação tinha uma única credencial da HubSpot usada por todas as integrações, colada em alguns fluxos e guardada em uma planilha compartilhada. Funcionava, até o dia em que um colaborador saiu e ninguém sabia ao certo onde aquele token estava em uso. Revogar significava arriscar derrubar processos críticos sem saber quais. O time ficou refém da própria credencial.

A reorganização foi separar a autenticação por finalidade: um token por integração, cada um com escopos mínimos, todos guardados em cofre. A partir daí, revogar um deixou de ser um evento traumático, porque ficou claro o que cada token alcança. O que parecia uma simplificação no começo, uma credencial para tudo, era na verdade uma bomba-relógio.

Checklist da autenticação bem feita

1. Você escolheu o tipo de credencial pelo número de portais e pelos recursos necessários, lembrando que webhooks exigem um app?
2. Cada token tem apenas os escopos mínimos da sua tarefa?
3. Leitura e escrita estão separadas em tokens diferentes quando faz sentido?
4. Os tokens estão guardados em cofre, nunca em código ou log?
5. Existe um token por integração, para revogação independente?
6. Em OAuth, a renovação do token de acesso está implementada e testada?
7. Há uma política de rotação e revogação imediata em caso de saída ou vazamento?

Perguntas frequentes

Qual credencial devo usar, app privado, OAuth ou service key?

App privado para integrar um único portal de forma interna, ou uma account service key para chamadas REST simples com escopo. OAuth para apps que vários portais vão instalar. E se você precisa de webhooks, app cards ou outras features de app, construa um app no novo developer platform. O número de portais e os recursos que você precisa decidem.

O que acontece se eu der escopos demais ao token?

O token funciona, mas o risco aumenta: se ele vazar, dá acesso a muito mais do que precisava. Siga o menor privilégio e conceda só os escopos da tarefa.

Onde guardo o token com segurança?

Em um cofre de credenciais: Postman Vault, gerenciador do n8n ou do Make, ou variáveis de ambiente protegidas. Nunca no corpo de uma coleção, em URL, em log ou em repositório de código.

Preciso renovar o token de app privado?

O token de app privado é fixo e não expira sozinho, mas você deve girá-lo periodicamente por segurança, e as account service keys têm rotação recomendada de cerca de seis meses. Já o token de acesso OAuth tem vida curta e precisa ser renovado pelo refresh token.

Por que usar um token por integração?

Para conseguir revogar um sem derrubar os outros e para auditar com clareza a origem de cada ação. Uma credencial única para tudo vira um ponto único de falha e de risco.

O que faço se um token vazar?

Revogue-o imediatamente e gere um novo, atualizando-o nas integrações que o usam. Se ele entrou no histórico de um repositório, apagar o arquivo não basta: a revogação é obrigatória. A HubSpot também pode desativar automaticamente um token exposto publicamente, mas não conte com isso.

Vai configurar uma integração e quer começar com a autenticação certa e segura? Na Insight Sales estruturamos apps, escopos e cofres de token seguindo boas práticas. Fale com a gente e descubra como podemos ajudar.