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:

  • aplicativos desenvolvidos para serem instalados em várias contas da HubSpot ou para listagem no Marketplace de aplicativos devem usar OAuth. 
  • os usuários que instalam aplicativos em suas contas da HubSpot devem ser superadministradores ou ter permissões de Acesso ao Marketplace de aplicativos.
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
cms.domains.read Os integradores podem listar domínios do CMS na conta de um cliente.  API do CMS Qualquer conta
cms.domains.write Os integradores podem criar, atualizar e excluir domínios personalizados do CMS.  API do CMS Qualquer conta
cms.functions.read Os integradores podem visualizar todas as funções sem servidor do CMS, quaisquer segredos relacionados e os resultados de execução das funções.  API do CMS CMS Hub Enterprise
cms.functions.write Os integradores podem gravar funções e segredos sem servidor no CMS. API do CMS CMS Hub Enterprise
cms.knowledge_base.articles.read Veja detalhes sobre os artigos da central de conhecimento. API do CMS Service Hub Professional ou Enterprise 

cms.knowledge_base.articles.write

Concede acesso para atualizar os artigos da central de conhecimento.  API do CMS Service Hub Professional ou Enterprise 
cms.knowledge_base.articles.publish Concede acesso para atualizar e publicar os artigos da central de conhecimento. API do CMS Service Hub Professional ou Enterprise 
cms.knowledge_base.settings.read Vejas as configurações gerais e de modelo da central de conhecimento, como o domínio ou o URL raiz. API do CMS Service Hub Professional ou Enterprise 
cms.knowledge_base.settings.write Concede acesso para atualizar as configurações gerais e de modelo da central de conhecimento. Isso inclui o acesso para escrever artigos da central de conhecimento. API do CMS Service Hub Professional ou Enterprise 
cms.performance.read Os integradores podem visualizar os dados de desempenho do CMS para todos os seus sites. API do CMS Qualquer conta
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.custom.read Veja detalhes sobre os objetos personalizados no CRM da HubSpot. Endpoints de objetos personalizados Qualquer Empresa
crm.objects.custom.write Crie, exclua ou altere objetos personalizados no CRM da HubSpot.  Endpoints de objetos personalizados Qualquer Empresa
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.feedback_submission.read Veja detalhes sobre os envios para qualquer uma de suas pesquisas de feedback. Endpoints de pesquisa de feedback Service Hub Professional ou Enterprise
crm.objects.goals.read Veja todos os tipos de meta.  Endpoints de metas Sales Hub StarterProfessional ou Enterprise
crm.objects.line_items.read Veja propriedades e outros detalhes sobre os itens de linha. Endpoints de itens de linha Qualquer conta
crm.objects.line_items.write Crie, exclua ou altere os itens de linha.  Endpoints de itens de linha Qualquer conta
crm.objects.marketing_events.read Veja detalhes sobre os eventos de marketing.  Endpoints de eventos de marketing Qualquer conta
crm.objects.marketing_events.write Crie, exclua ou altere os eventos de marketing.  Endpoints de eventos de marketing 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.objects.quotes.read Veja propriedades e outros detalhes sobre orçamentos e modelos de orçamento. Endpoints de orçamento Qualquer conta
crm.objects.quotes.write Crie, exclua ou altere os orçamentos. Endpoints de orçamento 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.custom.read Veja detalhes sobre as definições de objetos personalizados no CRM da HubSpot. Endpoints de objetos personalizados Qualquer Empresa
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
crm.schemas.line_items.read Veja detalhes sobre os itens de linha. Endpoints de itens de linha Qualquer conta
crm.schemas.quotes.read Veja detalhes sobre os orçamentos e modelos de orçamento. Endpoints de orçamento Qualquer conta
settings.billing.write Faça alterações nas configurações de cobrança da sua conta. Isso inclui gerenciar e atribuir licenças pagas aos usuários. Endpoints de configurações Qualquer conta
settings.currencies.read Lê as taxas de câmbio existentes, juntamente com a moeda atual da empresa associada ao seu portal.  Endpoints de informações da conta Qualquer conta
settings.currencies.write Crie, atualize e exclua taxas de câmbio, juntamente com a atualização da moeda da empresa associada ao seu portal.  Endpoints de informações da conta Qualquer conta
settings.users.read Veja detalhes sobre os usuários da conta e suas permissões. Endpoints de provisionamento de usuários Qualquer conta
settings.users.write Gerencie usuários e permissões de usuários na sua conta da HubSpot. Isso inclui a criação de novos usuários, a atribuição de permissões e funções e a exclusão de usuários existentes.  Endpoints de provisionamento de usuários Qualquer conta
settings.users.teams.read Veja detalhes sobre as equipes da conta.  Endpoints de provisionamento de usuários Qualquer conta
settings.users.team.write Atribua usuários a equipes em sua conta da HubSpot.  Endpoints de provisionamento de usuários Qualquer conta
account-info.security.read Inclui acesso a registos de atividade da conta e outras informações de segurança da conta.  API de atividade da conta Qualquer conta
accounting Permite que a HubSpot e a integração contábil compartilhem detalhes de faturas, produtos e contatos. API de extensão de contabilidade Qualquer conta
actions Adicione formulários às páginas do contato que realizam ações personalizadas. API de extensões do CRM Qualquer conta
analytics.behavioral_events.send Inclui acesso para enviar eventos comportamentais personalizados.  API de análise Marketing Hub Enterprise
automation Inclui fluxos de trabalho. API de automação (endpoints de Fluxos de trabalho) Marketing Hub Professional ou Enterprise
behavioral_events.event_definitions.read_write Crie, leia, atualize ou exclua eventos comportamentais. Isso inclui propriedades de eventos comportamentais.  API de análise Marketing Hub Enterprise
business_units.view.read Veja dados da unidade de negócios, incluindo as informações de logotipo. API de unidades de negócios Complemento para unidades de negócios
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
communication_preferences.read Veja detalhes das preferências de assinatura dos seus contatos.  API de preferências da assinatura Qualquer conta
communication_preferences.read_write Assine/cancele a assinatura de contatos para os seus tipos de assinatura. Isso não inscreverá contatos que cancelaram a assinatura.  API de preferências da assinatura Qualquer conta
communication_preferences.write Assine/cancele a assinatura de contatos para os seus tipos de assinatura. Isso não inscreverá contatos que cancelaram a assinatura.  API de preferências da assinatura 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
conversations.write Envie mensagens em conversas. Crie e atualize threads de mensagens. API de mensagens e caixa de entrada de Conversas Qualquer conta
crm.export Exporte registos do seu CRM para todos os tipos de dados de CRM. API de exportações do CRM  Qualquer conta
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
ctas.read Permite acesso de leitura para CTAs. Nenhuma API pública disponível Marketing Hub ou CMS Hub Starter, 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.

external_integrations.forms.access Inclui a capacidade de renomear, excluir e clonar formulários existentes. Endpoints de Formulários

Qualquer conta

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
files.ui_hidden.read Veja detalhes ou baixe arquivos de usuário, anexos e arquivos de sistema de todas as ferramentas do HubSpot.  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. Este escopo é adicionado por padrão a todos os aplicativos.   Qualquer conta
sales-email-read Concede acesso de leitura a todos os detalhes de e-mails individuais enviados a contatos. Endpoints de engajamentos

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
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


Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..