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 para todos os desenvolvedores de aplicativos: Qualquer aplicativo desenvolvido para ser instalado em várias contas do HubSpot ou para listagem no Marketplace de aplicativos deve usar o OAuth. Se você usar uma chave de API, sua lista de aplicativos será rejeitada. 

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

1. O primeiro passo para usar o OAuth é criar um aplicativo em uma conta do desenvolvedor da HubSpot. Depois disso, você encontrará o ID do cliente e o segredo do cliente de seu aplicativo na página de Autenticação das configurações do aplicativo.

MyHubSpotApp

 

2. Use o ID e o segredo do cliente, juntamente com os parâmetros de consulta e os escopos descritos abaixo, para criar seu URL de autorização. 

3. Direcione os usuários que estão instalando o aplicativo para o URL de autorização. Será exibida uma tela em que eles poderão selecionar uma conta (se tiverem várias contas) 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

 

4. Use o access_token para autenticar quaisquer chamadas API feitas para essa conta da HubSpot.

5. Assim que access_token expirar, use refresh_token da etapa 3 para gerar um novo access_token.


Observação: Seu aplicativo só aparecerá como um Aplicativo conectado em Configurações de integração de um usuário se você concluir as primeiras duas etapas. Você deve gerar o token de atualização e o token de acesso inicial para que o aplicativo apareça como “conectado”.


Parâmetros de consulta

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

 

Parâmetros obrigatórios
Parâmetro obrigatório Descrição Como usar
Client ID client_id=x
Usado no URL
Obtenha esse parâmetro na página de configurações de Autenticação do aplicativo (conforme descrito acima).
Redirect URL redirect_url=x
O URL para o 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 a que 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.

 

Veja a seguir o que é opcional:

 

Parâmetros opcionais
Parâmetro opcional Como usar Descrição
Escopos opcionais &optional_scope=x%20x Um conjunto de permissões opcionais separadas por espaço para 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 token 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 for incluído no URL de autorização, o valor será incluído em um parâmetro de consulta state 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 é redirecionado 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. 

Screen Shot 2020-03-26 at 4.21.46 PM

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.

 

Todos os escopos
 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
contacts Inclui contatos e listas. Endpoints de Contatos, Empresas, Negócios, Propriedades, Envolvimentos e Proprietários Qualquer conta
content  Inclui sites, páginas iniciais, CTA, 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.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 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, tíquetes 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 Sales Hub Professional ou Enterprise

Observação: É necessário atribuir uma licença paga do Sales Hub aos usuários para autorizar esse escopo.
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

Observação: O acesso a formulários também exige o escopo de contatos.
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 ou Enterprise ou Marketing Hub Professional ou Enterprise com o 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
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 envolvimentos de e-mail. Consulte a Visão geral de Envolvimentos para obter mais informações.
Service Hub Free, Starter, Professional ou Enterprise
social Inclui o Social Inbox. API de mídias sociais Marketing Hub Professional ou Enterprise
tickets Inclui acesso a tíquetes. Endpoints de tíquetes Service Hub Free, Starter, Professional ou Enterprise
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 o Complemento de e-mail transacional

 


Documentos relacionados

Métodos de Autenticação no HubSpot

Guia de início rápido do OAuth

Gerenciando tokens