Skip to main content
O OAuth é uma maneira segura de autenticação que usa tokens de autorização, em vez de uma senha, para conectar o aplicativo a uma conta de usuário. O primeiro passo para permitir que os usuários instalem o aplicativo em suas contas da HubSpot é iniciar o acesso ao OAuth.

​
Observação:

  • Qualquer aplicativo desenvolvido para ser instalado em várias contas do HubSpot ou para listagem no Marketplace de aplicativos deve usar o OAuth.
  • Os usuários que instalam aplicativos em suas contas da HubSpot devem ser superadministradores ou ter permissões de Acesso ao App Marketplace.

​
Recursos recomendados

  • O Guia de início rápido do OAuth ajudará você a começar a trabalhar usando um aplicativo de exemplo de trabalho.
  • Este tutorial da HubSpot Academy fornece uma rápida introdução sobre como usar o OAuth com o HubSpot. Ele detalha o fluxo do HubSpot-OAuth e mostra como atualizar um token de acesso.

​
Configurar autenticação OAuth

Para configurar a autenticação OAuth para seu aplicativo:
MyHubSpotApp
  • Use o ID e o segredo do cliente, juntamente com os parâmetros de consulta e os escopos descritos abaixo, para criar sua URL de autorização.
  • Direcione os usuários que estão instalando o aplicativo para a URL de autorização. Será exibida uma tela em que eles poderão selecionar uma conta e conceder acesso à integração. Você pode definir um URL de autorização específico para a conta da HubSpot adicionando o ID da conta entre /oauth/ e /authorize, como mostrado abaixo. Depois que o acesso for concedido, eles serão redirecionados ao aplicativo por meio de um redirect_url, que terá um parâmetro de consulta de código vinculado a ele. Você usará esse código e o segredo do cliente para obter um access_token  e um refresh_token da HubSpot.
    • Exemplo de URLs de autorização
      • Qualquer conta: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
      • Conta específica (ID 123456): https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
    • Exemplo de URL de redirecionamento: https://example.com/?code=xxxx
    • Exemplo de erro:https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
  • Use access_token para autenticar quaisquer chamadas API feitas para essa conta da HubSpot.
  • Uma vez que access_token expirar, use refresh_token para gerar um novo access_token.

​
Observação:

  • Seu aplicativo não aparecerá como um Aplicativo conectado na conta de um usuário, a menos que você gere o token de atualização e o token de acesso inicial.
  • Tokens de acesso refletem os escopos solicitados ao aplicativo e não refletem as permissões ou limitações do que um usuário pode fazer em sua conta da HubSpot. Por exemplo, se um usuário tiver permissões para visualizar apenas contatos de propriedade, mas autorizar uma solicitação para o escopo crm.objects.contacts.read, o token de acesso resultante poderá visualizar todos os contatos na conta e não apenas aqueles de propriedade do usuário que está autorizando.

​
Parâmetros de consulta

Os seguintes parâmetros de consulta são necessários ao criar uma URL de autorização para seu aplicativo: Os parâmetros a seguir são opcionais:

​
Configurar escopos

O OAuth exige que você defina escopos, ou permissões, para o aplicativo. Cada escopo fornece acesso a um conjunto de pontos de extremidade da API do HubSpot e permite que os usuários concedam a seu aplicativo acesso a ferramentas específicas em suas contas da HubSpot.
granular-scopes-selection
O acesso a APIs ou a pontos de extremidade depende da camada de conta da HubSpot. Se seu aplicativo permitir o uso de vários tipos de contas da HubSpot, você pode usar o parâmetro optional_scope para incluir quaisquer escopos em camadas que você usa. Dessa forma, clientes que usam contas gratuitas da HubSpot ainda podem autorizar seu aplicativo, mesmo que não consigam acessar todos os seus escopos. O aplicativo deve verificar e lidar com quaisquer escopos para o qual não seja autorizado. Uma lista completa de escopos está disponível aqui.

​
Documentos relacionados

Métodos de Autenticação no HubSpot Guia de início rápido do OAuth Gerenciando tokens
Última modificação em 10 de fevereiro de 2026