Autenticação
Trabalhando com OAuth
O OAuth é uma maneira segura de autenticação do aplicativo. Ele usa tokens de autorização, em vez de uma senha, para conectar seu aplicativo a uma conta de usuário.
Última modificação: 28 de agosto de 2025
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:- Primeiro, crie um aplicativo em uma conta de desenvolvedor da HubSpot. Depois de criar o aplicativo, você poderá encontrar o ID do cliente do aplicativo e o segredo do cliente na página Autenticação das configurações do aplicativo.
- 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 umredirect_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/
- Qualquer conta:
- 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
- Exemplo de URLs de autorização
-
Use
access_tokenpara autenticar quaisquer chamadas API feitas para essa conta da HubSpot. -
Uma vez que
access_tokenexpirar, userefresh_tokenpara gerar um novoaccess_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:| Parâmetro | Descrição | Como usar |
|---|---|---|
client_id | Um ID que serve como um identificador exclusivo para seu aplicativo. | Obtenha isso na página de configurações de autenticação do seu aplicativo (conforme descrito acima). |
redirect_uri | O URL para a qual os visitantes serão redirecionados após conceder acesso ao seu aplicativo. | Você também designará isso na página de configurações de autenticação do seu aplicativo. Observação: Por razões de segurança, este URL deve usar https em produção. (Ao testar usando localhost, http pode ser usado.) Você também deve usar um domínio, pois endereços IP não são aceitos. |
scope | Um conjunto de permissões separadas por espaços às quais seu aplicativo precisa ter acesso. | Todos os escopos que você marcou nas configurações do seu aplicativo Auth serão tratadas conforme necessário e você precisará incluí-las neste parâmetro ou a página de autorização exibirá um erro. Além disso, os usuários receberão um erro se tentarem instalar o aplicativo em uma conta que não tenha acesso a um escopo incluído. Consulte a documentação de referência de escopos para obter mais detalhes sobre quais endpoints podem ser acessados por escopos específicos. |
| Parâmetro | Como usar | Descrição |
|---|---|---|
optional_scope | Um conjunto separado por espaços de permissões opcionais para seu aplicativo. | Os escopos opcionais serão automaticamente removidos da solicitação de autorização se o usuário selecionar uma conta HubSpot que não tenha acesso a essa ferramenta (por exemplo, autorizar um escopo do Content Hub Enterprise em uma conta gratuita da HubSpot). Se estiver usando escopos opcionais, você precisará verificar o token de acesso ou o de atualização para ver quais foram concedidos. Confira o documentação de referência sobre escopos para obter mais detalhes. |
state | Se esse parâmetro estiver incluído no URL de autorização, o valor será incluído em um parâmetro de consulta de estado quando o usuário for direcionado para redirect_uri. | Um valor de string que pode ser usado para manter o estado do usuário quando ele é redirecionado ao aplicativo. |
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.
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.