Trabalhando com o OAuth

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. 

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.

Iniciando uma integração com OAuth 2.0

Para iniciar uma integração com OAuth 2.0:

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. 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 do HubSpot.
    • Exemplo de URL de autorização: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
    • Exemplo de URL de redirecionamento:https://www.example.com/?code=xxxx
    • Exemplo de erro: https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
  • Use o access_token para autenticar quaisquer chamadas API feitas para essa conta da HubSpot. 
  • Assim que access_token expirar, use refresh_token para gerar um novo access_token.

Observação:

  • o 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. 
  • os 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

Estes são os parâmetros obrigatórios quando se cria uma URL de autorização para o aplicativo:

Parâmetros obrigatórios
Parâmetro Descrição Como usar
Client ID client_id=x
Usado na URL		 Obtenha esse parâmetro na página de configurações de Autenticação do aplicativo (conforme descrito acima).
URL de redirecionamento redirect_uri=x
O URL para a qual os visitantes serão redirecionados depois da concessão de acesso ao aplicativo.

Você também atribuirá esse parâmetro na página de configurações de Autenticação do aplicativo.

Observação: por motivos de segurança, esse URL deve usar https na produção. (Ao testar o uso de localhost, o httpp pode ser usado.) Você também deve usar um domínio, pois endereços IP não são aceitos.
Scope scope=x%20x

Um conjunto de permissões separadas por espaço para o qual o seu aplicativo precisa ter acesso. Qualquer escopo que você tenha marcado nas configurações de Autenticação do aplicativo será considerado obrigatório e precisará ser incluído neste parâmetro; caso contrário, 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 tabela de Escopos abaixo para obter mais informações sobre quais endpoints podem ser acessados por escopos específicos.

Os parâmetros a seguir são opcionais:

Parâmetros opcionais
Parâmetro Como usar Descrição
Escopos opcionais &optional_scope=x%20x Um conjunto de permissões opcionais separadas por espaço para o seu aplicativo. Os escopos opcionais serão retirados automaticamente da solicitação de autorização se o usuário selecionar uma conta da HubSpot que não tenha acesso a essa ferramenta (como solicitar o escopo social em um portal somente CRM). Se estiver usando escopos opcionais, você precisará verificar o token de acesso ou o de atualização para ver quais foram concedidos. Veja a tabela abaixo para obter mais detalhes sobre os escopos.
Estado &state=y
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_url.		 Um valor de string que pode ser usado para manter o estado do usuário quando ele for redirecionado de volta ao aplicativo. 

Escopos

O OAuth exige que você defina escopos, ou permissões, para o aplicativo. Cada escopo fornece acesso a um conjunto de endpoints 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 endpoints depende da camada de conta da HubSpot. Veja na tabela abaixo uma lista completa dos escopos e endpoints acessíveis. 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 com que trabalha. Dessa forma, os clientes que usarem contas apenas CRM poderão continuar a autorizar seu aplicativo, mesmo que não consigam acessar todos os escopos dele. O aplicativo deve verificar e lidar com quaisquer escopos para o qual não seja autorizado.


 Escopo Descrição Fornece acesso a Camada de conta obrigatória
automation Inclui fluxos de trabalho. API de automação (endpoints de Fluxos de trabalho) Marketing Hub Professional ou Enterprise
business-intelligence Inclui endpoints que estão na parte superior de origens e e-mails. API de análise Qualquer conta
collector.graphql_query.execute Consulte dados da sua conta da HubSpot usando o endpoint da API GraphQL Endpoint da API GraphQL CMS Hub Professional ou Enterprise
collector.graphql_schema.read Realize consultas de introspecção por meio de clientes de aplicativos GraphQL, como GraphiQL GraphiQL e outros clientes GraphQL de terceiros CMS Hub Professional ou Enterprise
crm.lists.read Exiba detalhes sobre listas de contatos. Listar endpoints Qualquer conta
crm.lists.write Crie, exclua ou faça alterações nas listas de contatos Listar endpoints Qualquer conta
crm.objects.companies.read Exiba propriedades e outros detalhes sobre as empresas. Endpoints de empresas Qualquer conta
crm.objects.companies.write Exiba as propriedades e crie, exclua ou altere as empresas. Endpoints de empresas Qualquer conta
crm.objects.contacts.read Exiba as propriedades e outros detalhes sobre os contatos. Endpoints de contatos Qualquer conta
crm.objects.contacts.write Visualize propriedades e crie, exclua e faça alterações nos contatos. Endpoints de contatos Qualquer conta
crm.objects.deals.read Exiba propriedades e outros detalhes sobre os negócios. Endpoints de negócio Qualquer conta
crm.objects.deals.write Exiba as propriedades e crie, exclua ou altere os negócios. Endpoints de negócio Qualquer conta
crm.objects.owners.read Exiba detalhes sobre os usuários atribuídos a um registro de CRM. Endpoints de proprietários Qualquer conta
crm.schemas.companies.read Exiba detalhes sobre as configurações de propriedades para empresas. Endpoints de propriedades Qualquer conta
crm.schemas.companies.write Crie, exclua ou faça alterações nas configurações de propriedade das empresas. Endpoints de propriedades Qualquer conta
crm.schemas.contacts.read Exiba detalhes sobre as configurações de propriedade dos contatos. Endpoints de propriedades. Qualquer conta
crm.schemas.contacts.write Crie, exclua ou faça alterações nas configurações de propriedade dos contatos. Endpoints de propriedades Qualquer conta
crm.schemas.deals.read Visualize detalhes sobre as configurações de propriedade dos negócios. Endpoints de propriedades Qualquer conta
crm.schemas.deals.write Crie, exclua ou faça alterações nas configurações de propriedade dos negócios. Endpoints de propriedades Qualquer conta
content  Inclui sites, páginas iniciais, e-mail, blog e campanhas. API do CMS e endpointos de Calendário, E-mail e Eventos de e-mail CMS Hub Professional ou Enterprise ou Marketing Hub Professional ou Enterprise
conversations.read Veja detalhes sobre os threads na caixa de entrada de conversas. API de mensagens e caixa de entrada de Conversas Qualquer conta
conversations.visitor_identification.tokens.create  Extraia os tokens de identificação para os visitantes do site autenticados que estão interagindo com o widget de chat da HubSpot. API de identificação do visitante Qualquer Professional ou Enterprise
crm.import Permite importar registros para o CRM. Inclui a criação de novos registros ou a modificação de qualquer um de seus registros existentes para todos os tipos de dados de CRM (contatos, empresas, negócios, tickets etc). Não inclui o arquivamento nem a exclusão de dados. API de importações do CRM Qualquer conta
cms.source_code.read_write Permite carregar e baixar modelos, módulos e outros arquivos de que os desenvolvedores precisam para escrever o código para sites e e-mails. API do Mapeador de arquivos de conteúdo, API de Módulos do CMS, Layouts do CMS, API de Modelos do CMS CMS Hub Professional ou Enterprise ou Marketing Hub Professional ou Enterprise
e-commerce Inclui acesso a recursos de e-commerce. Endpoints de produtos e itens de linha

Qualquer conta

Observação: somente as contas do Professional e Enterprise podem usar esse escopo para a API de produtos.
files Inclui acesso ao Gerenciador de arquivos. Arquivos (Gerenciador de arquivos) e endpoints do mapeador de arquivos (layout, módulos e modelos de CMS) Qualquer conta
forms Inclui acesso aos endpoints de Formulários. Endpoints de Formulários Qualquer conta
forms-uploaded-files Baixe arquivos enviados por meio de um formulário. Obtenha um arquivo carregado por meio de um endpoint de envio de formulário Qualquer conta
hubdb Inclui acesso ao HubDB. Endpoints do HubDB CMS Hub Professional u Enterprise ou Marketing Hub Professional ou Enterprise com Complemento do site
integration-sync Exibe a API de sincronização, que permite sincronizar a maioria dos objetos do CRM. API do E-commerce Bridge Qualquer conta
media_bridge.read Concede acesso a eventos e objetos a partir do media bridge. API de Media Bridge Qualquer conta
media_bridge.write Concede acesso para criar e atualizar eventos e objetos do media bridge. API de Media Bridge Qualquer conta
oauth Escopo básico obrigatório para OAuth.   Qualquer conta
sales-email-read Concede acesso de leitura a todos os detalhes de e-mails individuais enviados a contatos. Endpoints de envolvimento

Observação: este escopo é obrigatório para obter o conteúdo dos engajamentos de e-mail. Consulte a Visão geral de Envolvimentos para obter mais informações.		 Qualquer conta
settings.user.read Recupera os usuários e as funções dos usuários de uma conta da HubSpot. API de provisionamento de usuários

Qualquer conta

Observação: somente as contas do Enterprise podem usar este escopo para recuperar funções de usuários.
settings.user.teams.read Recupera as equipes de uma conta da HubSpot. API de provisionamento de usuários

Qualquer Professional ou Enterprise
social Inclui o Social Inbox. API de mídias sociais Marketing Hub Professional ou Enterprise
tickets Inclui acesso a tickets. Endpoints de tickets Qualquer conta
timeline Concede acesso para gerenciar eventos personalizados em registros do HubSpot CRM. Inclui a criação ou a atualização de registros. Endpoints de Eventos da linha do tempo Qualquer conta
transactional-email Inclui e-mails transacionais e os endpoints deles. Endpoints de e-mail transacionais Marketing Hub Professional ou Enterprise com Complemento de e-mail transacional

Documentos relacionados

Métodos de Autenticação no HubSpot

Guia de início rápido do OAuth

Gerenciando tokens