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.
- 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.
Para iniciar uma integração com OAuth 2.0:
- 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_token
para autenticar quaisquer chamadas API feitas para essa conta da HubSpot. -
Uma vez que
access_token
expirar, userefresh_token
para gerar um novoaccess_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.
Estes são os parâmetros obrigatórios quando se cria uma URL de autorização para o aplicativo:
Parâmetro | Descrição | Como usar |
---|---|---|
ID do cliente | client_id=x Usado no 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 o qual os visitantes serão redirecionados depois que receberem 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. |
Escopo | 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 Escopos abaixo para obter mais detalhes sobre quais pontos de extremidade podem ser acessados por escopos específicos. |
Os parâmetros a seguir são 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 é redirecionado ao aplicativo. |
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.
O acesso a APIs ou a pontos de extremidade depende da camada de conta da HubSpot. Veja na tabela abaixo uma lista completa dos escopos e pontos de extremidade 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 que você usa. 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 | Oferece acesso a | Categoria de conta necessá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 de conhecimento. | API do CMS | Service Hub Professional ou Enterprise |
cms.knowledge_base.articles.write | Concede acesso para atualizar artigos de conhecimento. | API do CMS | Service Hub Professional ou Enterprise |
cms.knowledge_base.articles.publish | Concede acesso para atualizar e publicar artigos 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 | Veja detalhes sobre listas de contato | Pontos de extremidade de listas | Qualquer conta |
crm.lists.write | Criar, excluir ou fazer alterações nas listas de contatos | Listar pontos de extremidade | Qualquer conta |
crm.objects.companies.read | Veja propriedades e outros detalhes sobre as empresas. | Pontos de extremidade de empresas | Qualquer conta |
crm.objects.companies.write | Exiba as propriedades e crie, exclua ou altere as empresas. | Pontos de extremidade de empresas | Qualquer conta |
crm.objects.contacts.read | Veja as propriedades e outros detalhes sobre os contatos. | Pontos de extremidade de contatos | Qualquer conta |
crm.objects.contacts.write | Visualize propriedades e crie, exclua e faça alterações nos contatos. | Pontos de extremidade de contatos | Qualquer conta |
crm.objects.custom.read | Veja detalhes sobre os objetos personalizados no CRM da HubSpot. | Pontos de extremidade de objetos personalizados | Qualquer Enterprise |
crm.objects.custom.write | Crie, exclua ou faça alterações em objetos personalizados no CRM da HubSpot. | Pontos de extremidade de objetos personalizados | Qualquer Enterprise |
crm.objects.deals.read | Veja propriedades e outros detalhes sobre negócios. | Pontos de extremidade de negócios | Qualquer conta |
crm.objects.deals.write | Exiba as propriedades e crie, exclua ou altere os negócios. | Pontos de extremidade de negócios | Qualquer conta |
crm.objects.feedback_submission.read | Veja detalhes sobre os envios para qualquer uma de suas pesquisas de feedback. | Pontos de extremidade de pesquisa de comentários | Service Hub Professional ou Enterprise |
crm.objects.goals.read | Veja todos os tipos de meta. | Pontos de extremidade de metas | Sales Hub Starter, Professional ou Enterprise |
crm.objects.line_items.read | Exibir propriedades e outros detalhes sobre itens de linha | Pontos de extremidade de itens de linha | Qualquer conta |
crm.objects.line_items.write | Crie, exclua ou faça alterações no itens de linha. | Pontos de extremidade de itens de linha | Qualquer conta |
crm.objects.marketing_events.read | Veja detalhes sobre os eventos de marketing. | Pontos de extremidade de eventos de marketing | Qualquer conta |
crm.objects.marketing_events.write | Crie, exclua ou faça alterações em eventos de marketing. | Pontos de extremidade de eventos de marketing | Qualquer conta |
crm.objects.owners.read | Exiba detalhes sobre os usuários atribuídos a um registro de CRM. | Pontos de extremidade de proprietários | Qualquer conta |
crm.objects.quotes.read | Veja propriedades e outros detalhes sobre orçamentos e modelos de orçamento. | Pontos de extremidade de orçamentos | Qualquer conta |
crm.objects.quotes.write | Crie, exclua ou faça alterações nos orçamentos. | Pontos de extremidade de orçamentos | Qualquer conta |
crm.schemas.companies.read | Veja detalhes sobre as configurações de propriedades para empresas. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.companies.write | Crie, exclua ou faça alterações nas configurações de propriedades das empresas. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.contacts.read | Veja detalhes sobre as configurações de propriedade dos contatos. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.contacts.write | Crie, exclua ou altere as configurações de propriedade dos contatos. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.custom.read | Veja detalhes sobre as definições de objetos personalizados no CRM da HubSpot. | Pontos de extremidade de objetos personalizados | Qualquer Enterprise |
crm.schemas.deals.read | Veja detalhes sobre as configurações de propriedade dos negócios. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.deals.write | Crie, exclua ou altere as configurações de propriedades dos negócios. | Pontos de extremidade de propriedades | Qualquer conta |
crm.schemas.line_items.read | Veja detalhes sobre itens de linha. | Pontos de extremidade de itens de linha | Qualquer conta |
crm.schemas.quotes.read | Veja detalhes sobre orçamentos e modelos de orçamento. | Pontos de extremidade de orçamentos | 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. | Pontos de extremidade 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. | Pontos de extremidade 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. | Pontos de extremidade de informações da conta | Qualquer conta |
settings.users.read | Veja detalhes sobre os usuários da conta e suas permissões. | Pontos de extremidade 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. | Pontos de extremidade de provisionamento de usuários | Qualquer conta |
settings.users.teams.read | Veja detalhes sobre as equipes da conta. | Pontos de extremidade de provisionamento de usuários | Qualquer conta |
settings.users.team.write | Atribua usuários a equipes em sua conta da HubSpot. | Pontos de extremidade de provisionamento de usuários | Qualquer conta |
account-info.security.read | Inclui acesso a registros 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 contato |
analytics.behavioral_events.send | Inclui acesso para enviar eventos comportamentais personalizados. | API de análises | Marketing Hub Enterprise |
automation | Isso inclui fluxos de trabalho. | API de automação (Pontos de extremidade de fluxos de trabalho) | Marketing Hub Professional ou Enterprise |
behavioral_events.event_definitions.read_write | Crie, leia, atualize ou exclua eventos comportamentais. Inclui propriedades de eventos comportamentais. | API de análises | 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 de Unidades de negócios |
business-intelligence | Inclui pontos de extremidade 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 ponto de extremidade da API do GraphQL | Ponto de extremidade da API do 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 de seus contatos. | API de preferências de 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 de 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 de assinatura | Qualquer conta |
content | Inclui sites, landing pages, e-mail, blog e campanhas. | API do CMS e pontos de extremidade 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 publicAPI disponível | Marketing Hub ou CMS Hub Starter, Professional ou Enterprise |
e-commerce | Inclui acesso aos recursos de e-commerce. | Pontos de extremidade de produtos e itens de linha | Qualquer conta |
external_integrations.forms.access | Inclui a capacidade de renomear, excluir e clonar formulários existentes. | Pontos de extremidade de formulários | Qualquer conta |
files | Isso inclui acesso ao Gerenciador de arquivos. | Arquivos (Gerenciador de arquivos) e pontos de extremidade 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 pontos de extremidade do mapeador de arquivos (modelos, módulos e layout CMS) | Qualquer conta |
forms | Inclui acesso aos pontos de extremidade de formulários. | Pontos de extremidade de provisionamento de formulários | Qualquer conta |
forms-uploaded-files | Baixe arquivos enviados por meio de um formulário. | Obter um arquivo carregado por meio de um ponto de extremidade de envio de formulário | Qualquer conta |
hubdb | Isso inclui acesso ao HubDB. | Pontos de extremidade HubDB | CMS Hub Professional ou Enterprise ou Marketing Hub Professional ou Enterprise com o Complemento de site |
integration-sync | Exibe a API de sincronização, que permite sincronizar a maioria dos objetos do CRM. | API de ponte de comércio eletrônico | Qualquer conta |
media_bridge.read | Concede acesso a eventos e objetos 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 para ler todos os detalhes de e-mails individuais enviados aos contatos. | Pontos de extremidade de engajamentosObservação: este escopo é necessário para obter o conteúdo dos engajamentos de e-mail. Consulte a Visão geral de Engajamentos para obter mais informações. | Qualquer conta |
social | Inclui a caixa de entrada social. | API de mídia social | Marketing Hub Professional ou Enterprise |
tickets | Inclui acesso a tickets. | Pontos de extremidade 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. | Pontos de extremidade de eventos da linha do tempo | Qualquer conta |
transactional-email | Inclui e-mails transacionais e pontos de extremidade de e-mails transacionais. | Pontos de extremidade de e-mails transacionais | **Marketing Hub** Professional ou Enterprise com o Complemento de e-mail transacional |