App público vs app privado na HubSpot: qual escolher

Use um app privado quando estiver integrando com uma única conta da HubSpot que você controla: as automações internas do seu próprio portal, scripts e integrações personalizadas. Uma atualização para 2026: para integrações de conta única que só mexem com dados (sincronizações, scripts, conectores de BI), a HubSpot agora aponta as service keys de conta como a credencial recomendada e trata os apps privados criados na interface do portal como legados. Um app privado ainda faz sentido quando você precisa de webhooks. Use um app público quando a integração for instalada em múltiplas contas da HubSpot: um produto que você vende, uma listagem no marketplace ou qualquer coisa que os clientes conectam sozinhos. Apps privados autenticam com um token de acesso estático que não expira e pode ser rotacionado; apps públicos exigem OAuth 2.0, com access tokens de 30 minutos e refresh tokens. Se você precisa de uma listagem no App Marketplace, o app público é obrigatório.

Se você está construindo sobre as APIs da HubSpot em 2026, essa é a primeira decisão de arquitetura que vai tomar, e vale a pena acertar, porque ela determina o seu modelo de autenticação, as suas opções de distribuição e quanta infraestrutura você vai precisar manter. Este guia compara os dois tipos de app nos critérios que realmente importam, cobre o que a nova plataforma de desenvolvedor da HubSpot muda e entrega um framework de decisão que você aplica em cinco minutos.

Principais pontos

• Apps privados = uma conta da HubSpot, token estático rotacionável, configuração em minutos, até 20 por conta. Sem listagem no marketplace. A HubSpot agora trata os apps privados criados na interface como legados; para integrações de conta única só de dados, as service keys de conta são a credencial recomendada.
• Apps públicos = muitas contas da HubSpot, OAuth 2.0 obrigatório, conta de desenvolvedor obrigatória, elegíveis para o App Marketplace, além de recursos como timeline events.
• Os dois tipos usam os mesmos escopos e as mesmas APIs: migrar de privado para público depois é tranquilo.
• Na plataforma de desenvolvedor 2025.2 da HubSpot, a escolha agora é enquadrada como distribuição (privada vs. marketplace) mais autenticação (token estático vs. OAuth), e apps de distribuição privada agora também podem usar OAuth.
• A criação de apps públicos legados foi encerrada em 23 de junho de 2026: apps públicos novos precisam ser construídos na plataforma de desenvolvedor atual (projects + CLI). Os apps legados existentes continuam funcionando.
• OAuth em apps públicos significa gestão de refresh tokens: armazenamento, rotação e fluxos de reautorização ficam por sua conta.

O que é um app privado da HubSpot?

Um app privado é uma integração com escopo em uma conta específica da HubSpot. Você o cria direto no seu portal (Configurações → Integrações → Apps Privados, ou via projects na nova plataforma de desenvolvedor), escolhe os escopos de que ele precisa, e a HubSpot emite um token de acesso estático na hora. Sem dança de OAuth, sem redirect URLs, sem lógica de refresh de token: você coloca o token no seu gerenciador de secrets e começa a chamar as APIs. Note que a HubSpot agora rotula esses apps privados criados na interface como legados. Desde fevereiro de 2026, o caminho recomendado para novas integrações sistema a sistema em uma conta é uma service key de conta (Configurações → Integrações → Service Keys, em beta público), que te dá a mesma credencial estática com rotação e log de auditoria, mas sem suporte a webhooks. O app privado continua sendo a opção quando a sua integração de conta única precisa de webhooks.

Características principais, segundo a documentação de apps privados da HubSpot:

• O token nunca expira, mas você pode rotacioná-lo a qualquer momento se for comprometido.
• Cada conta pode ter até 20 apps privados, cada um com seus próprios escopos, o que é útil para dividir permissões por trabalho (um app para uma sincronização de dados, outro para um script de relatórios).
• Apps privados suportam assinaturas de webhook sobre mudanças em objetos do CRM, embora nos apps privados legados as assinaturas sejam editadas na interface de configurações do app, não programaticamente.
• Os rate limits de rajada são por app (100 requisições/10s no Free/Starter, 190/10s no Professional/Enterprise, até 200/10s com o add-on de API), enquanto os limites diários são compartilhados pela conta.

O que é um app público da HubSpot?

Um app público é uma integração desenhada para ser instalada em muitas contas da HubSpot: as dos seus clientes, não só a sua. Ele vive em uma conta de desenvolvedor, autentica exclusivamente via OAuth 2.0 e é o único tipo de app elegível para uma listagem no App Marketplace da HubSpot (depois de passar pela revisão da HubSpot).

A exigência de OAuth muda a sua realidade de engenharia: os usuários instalam com um clique, e o seu app recebe um access token de 30 minutos mais um refresh token de longa duração por portal instalado. Isso significa construir armazenamento de tokens, refresh proativo e fluxos de reautorização, o checklist de produção completo que cobrimos no nosso guia do erro de invalid refresh token da HubSpot, com os fundamentos no de autenticação e apps na API da HubSpot. Em troca, os apps públicos destravam capacidades que os privados não têm, incluindo timeline events personalizados nos registros do CRM e páginas de configurações do app dentro do portal do cliente.

App público vs app privado: comparação lado a lado

Os dois tipos de app aceitam os mesmos escopos OAuth e usam métodos de requisição idênticos, como o próprio guia comparativo da HubSpot aponta, o que torna começar privado e migrar para público depois um caminho de baixo risco.

Como escolher entre um app público e um privado?

Faça três perguntas, nesta ordem:

1. Quantas contas da HubSpot isso vai tocar? Uma conta, a sua ou a de um único cliente, aponta para uma credencial de conta única: uma service key de conta se a integração só lê e escreve dados, ou um app privado se ela também precisa de webhooks. Mais de uma, ou “ainda não sabemos, mas clientes vão instalar”, aponta para um app público. Esse é o fator dominante; quase todo o resto decorre dele.

2. Você precisa de distribuição no marketplace ou de recursos exclusivos de app público? Uma listagem no App Marketplace exige um app público, ponto final. O mesmo vale se você precisa de timeline events personalizados em registros de contato, empresa ou negócio. Se a sua integração é uma custom code action de workflow, uma sincronização de dados ou um script de relatórios, um app privado dá conta.

3. Quanta infraestrutura de autenticação você quer carregar? Um app privado é um secret em um cofre. Um app público é um armazenamento de tokens, lógica de refresh, tratamento de condições de corrida e fluxos de reconexão para cada portal instalado. Se você não tem capacidade de engenharia para esse ciclo de vida, não o assuma antes de precisar.

Um padrão comum do mundo real, ecoado nas discussões da comunidade da HubSpot: os times adotam apps privados com escopos bem escolhidos para tudo que é interno, e só partem para um app público quando a distribuição multiconta aparece de verdade no roadmap.

O que muda com a plataforma de desenvolvedor 2025.2 da HubSpot?

Se você leu tutoriais antigos, note que a HubSpot vem remodelando como os apps são construídos. Na plataforma de desenvolvedor atual, os apps são definidos em código, como um project publicado via CLI da HubSpot, com a configuração em um arquivo app-hsmeta.json, e a pergunta público/privado é reenquadrada em dois eixos:

• Distribuição: privada (a sua conta) ou marketplace (qualquer um pode instalar)
• Autenticação: token estático (só na distribuição privada) ou OAuth (disponível nas duas, obrigatório para o marketplace)

A consequência prática: agora dá para construir um app de distribuição privada que usa OAuth, um meio-termo que não existia no modelo legado, útil quando você quer as propriedades de segurança do OAuth sem uma listagem no marketplace. Os apps OAuth de marketplace ganham o acesso mais amplo a recursos (app cards, webhooks, funções serverless).

Duas datas para planejar: a criação de apps públicos legados foi encerrada em 23 de junho de 2026 (os apps legados existentes continuam suportados, mas os novos apps públicos são construídos na plataforma atual), e a documentação mais antiga da HubSpot agora rotula os apps privados/públicos clássicos como “legados”; eles continuam funcionando com todas as APIs REST, mas os novos recursos da plataforma chegam primeiro aos apps construídos com projects.

Dá para começar com um app privado e mudar para público depois?

Sim, e essa é muitas vezes a sequência certa. Como os escopos e as chamadas de API são idênticos, a migração é essencialmente uma troca de autenticação: substituir o cabeçalho do token estático pelo ciclo de vida de tokens do OAuth, registrar uma redirect URL e construir o fluxo de instalação. A sua lógica de negócio, as chamadas de API em si, não muda. A HubSpot também publica um caminho de migração para o framework de projects para mover apps existentes para a plataforma atual.

A armadilha a evitar é o contrário: entregar um app público para um único cliente “por garantia” e carregar por anos uma infraestrutura de OAuth de que você não precisava. Case a ferramenta com a necessidade real de distribuição.

Por que essa decisão é uma questão de RevOps, não só de engenharia

A arquitetura de apps determina quem pode ver e mudar o quê no seu CRM. Vinte apps privados com permissões bem delimitadas são uma superfície de governança; um app OAuth instalado nos portais dos clientes é um acordo de acesso a dados. Se o seu time trata saúde de integrações, higiene de permissões e observabilidade de API como parte de Revenue Operations, com donos e dashboards, a decisão público/privado vira um trade-off explícito em vez de um acidente.

Perguntas frequentes

Qual é a principal diferença entre um app público e um app privado da HubSpot?

Distribuição e autenticação. Um app privado se conecta a uma conta da HubSpot usando um token de acesso estático que não expira. Um app público pode ser instalado em contas ilimitadas, autentica via OAuth 2.0 com refresh tokens e é o único tipo elegível para o App Marketplace da HubSpot.

Apps privados da HubSpot suportam webhooks?

Sim. Apps privados podem assinar webhooks de mudanças em objetos do CRM (criações, atualizações, exclusões). Nos apps privados legados, as assinaturas de webhook são gerenciadas na interface de configurações do app, e não programaticamente via API.

Quantos apps privados posso criar em uma conta da HubSpot?

Até 20 apps privados por conta da HubSpot. Cada um tem seu próprio token de acesso e escopos, o que permite dividir as permissões entre integrações diferentes em vez de compartilhar um único token com privilégios demais.

Os tokens de app privado expiram?

Não. Os tokens de acesso de apps privados são estáticos e nunca expiram por cronograma. Você pode rotacionar o token manualmente a qualquer momento, por exemplo depois de uma suspeita de vazamento, o que invalida imediatamente o token antigo.

Um app privado pode ser listado no App Marketplace da HubSpot?

Não. As listagens no marketplace exigem um app público (distribuição de marketplace na plataforma atual), que precisa autenticar via OAuth e passar pelo processo de revisão de apps da HubSpot.

Um app público da HubSpot é mais difícil de construir que um privado?

Sim, principalmente por causa do OAuth. Um app público exige uma conta de desenvolvedor, um fluxo de instalação/autorização e gestão de tokens por portal: armazenar refresh tokens, renovar access tokens de 30 minutos e tratar revogações. Um app privado não precisa de nada disso.

Os escopos de API são diferentes entre apps públicos e privados?

Não. Os dois tipos usam os mesmos escopos e as mesmas APIs REST, e as requisições são feitas do mesmo jeito. É por isso que migrar uma integração de privada para pública é, na maior parte, uma mudança de autenticação, não uma reescrita.

O que aconteceu com os apps públicos legados em 2026?

A HubSpot encerrou a criação de apps públicos legados em 23 de junho de 2026. Os apps legados existentes continuam funcionando e suportados, mas os novos apps públicos são construídos na plataforma de desenvolvedor atual usando projects, a CLI da HubSpot e uma configuração em app-hsmeta.json.

Um app privado pode usar OAuth na nova plataforma de desenvolvedor?

Sim. Na plataforma de desenvolvedor 2025.2 da HubSpot, distribuição (privada vs. marketplace) e autenticação (token estático vs. OAuth) são escolhas separadas, então um app de distribuição privada pode autenticar com OAuth, uma opção que não existia no modelo legado.