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.
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. 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
- Exemplo de URL de autorização:
- Use o
access_token
para autenticar quaisquer chamadas API feitas para essa conta da HubSpot. - Assim 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 |
---|---|---|
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. |
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 for redirecionado de volta ao aplicativo. |
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.
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 |
|
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 Starter, Professional 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 |
Agradecemos pelos seus comentários. Eles são muito importantes para nós.