Ignorar e ir ao conteúdo principal

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.

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

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. 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 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 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/
    • 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
  • Use access_token para autenticar quaisquer chamadas API feitas para essa conta da HubSpot.

  • Uma vez que access_token expirar, use refresh_token para gerar um novo access_token.

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

ParâmetroDescriçãoComo usar
ID do clienteclient_id=xUsado no URLObtenha esse parâmetro na página de configurações de Autenticação do aplicativo (conforme descrito acima).
URL de redirecionamentoredirect_uri=xO 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.
Escoposcope=x%20xUm 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âmetroComo usarDescrição
Escopos opcionais&optional_scope=x%20xUm 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=ySe 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.

granular-scopes-selection

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.

EscopoDescriçãoOferece acesso aCategoria de conta necessária
cms.domains.readOs integradores podem listar domínios do CMS na conta de um cliente.API do CMSQualquer conta
cms.domains.writeOs integradores podem criar, atualizar e excluir domínios personalizados do CMS.API do CMSQualquer conta
cms.functions.readOs 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 CMSCMS Hub Enterprise
cms.functions.writeOs integradores podem gravar funções e segredos sem servidor no CMS.API do CMSCMS Hub Enterprise
cms.knowledge_base.articles.readVeja detalhes sobre os artigos de conhecimento.API do CMSService Hub Professional ou Enterprise
cms.knowledge_base.articles.writeConcede acesso para atualizar artigos de conhecimento.API do CMSService Hub Professional ou Enterprise
cms.knowledge_base.articles.publishConcede acesso para atualizar e publicar artigos de conhecimento.API do CMSService Hub Professional ou Enterprise
cms.knowledge_base.settings.readVejas as configurações gerais e de modelo da central de conhecimento, como o domínio ou o URL raiz.API do CMSService Hub Professional ou Enterprise
cms.knowledge_base.settings.writeConcede 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 CMSService Hub Professional ou Enterprise
cms.performance.readOs integradores podem visualizar os dados de desempenho do CMS para todos os seus sites.API do CMSQualquer conta
crm.lists.readVeja detalhes sobre listas de contatoPontos de extremidade de listasQualquer conta
crm.lists.writeCriar, excluir ou fazer alterações nas listas de contatosListar pontos de extremidadeQualquer conta
crm.objects.companies.readVeja propriedades e outros detalhes sobre as empresas.Pontos de extremidade de empresasQualquer conta
crm.objects.companies.writeExiba as propriedades e crie, exclua ou altere as empresas.Pontos de extremidade de empresasQualquer conta
crm.objects.contacts.readVeja as propriedades e outros detalhes sobre os contatos.Pontos de extremidade de contatosQualquer conta
crm.objects.contacts.writeVisualize propriedades e crie, exclua e faça alterações nos contatos.Pontos de extremidade de contatosQualquer conta
crm.objects.custom.readVeja detalhes sobre os objetos personalizados no CRM da HubSpot.Pontos de extremidade de objetos personalizadosQualquer Enterprise
crm.objects.custom.writeCrie, exclua ou faça alterações em objetos personalizados no CRM da HubSpot.Pontos de extremidade de objetos personalizadosQualquer Enterprise
crm.objects.deals.readVeja propriedades e outros detalhes sobre negócios.Pontos de extremidade de negóciosQualquer conta
crm.objects.deals.writeExiba as propriedades e crie, exclua ou altere os negócios.Pontos de extremidade de negóciosQualquer conta
crm.objects.feedback_submission.readVeja detalhes sobre os envios para qualquer uma de suas pesquisas de feedback.Pontos de extremidade de pesquisa de comentáriosService Hub Professional ou Enterprise
crm.objects.goals.readVeja todos os tipos de meta.Pontos de extremidade de metasSales Hub Starter, Professional ou Enterprise
crm.objects.line_items.readExibir propriedades e outros detalhes sobre itens de linhaPontos de extremidade de itens de linhaQualquer conta
crm.objects.line_items.writeCrie, exclua ou faça alterações no itens de linha.Pontos de extremidade de itens de linhaQualquer conta
crm.objects.marketing_events.readVeja detalhes sobre os eventos de marketing.Pontos de extremidade de eventos de marketingQualquer conta
crm.objects.marketing_events.writeCrie, exclua ou faça alterações em eventos de marketing.Pontos de extremidade de eventos de marketingQualquer conta
crm.objects.owners.readExiba detalhes sobre os usuários atribuídos a um registro de CRM.Pontos de extremidade de proprietáriosQualquer conta
crm.objects.quotes.readVeja propriedades e outros detalhes sobre orçamentos e modelos de orçamento.Pontos de extremidade de orçamentosQualquer conta
crm.objects.quotes.writeCrie, exclua ou faça alterações nos orçamentos.Pontos de extremidade de orçamentosQualquer conta
crm.schemas.companies.readVeja detalhes sobre as configurações de propriedades para empresas.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.companies.writeCrie, exclua ou faça alterações nas configurações de propriedades das empresas.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.contacts.readVeja detalhes sobre as configurações de propriedade dos contatos.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.contacts.writeCrie, exclua ou altere as configurações de propriedade dos contatos.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.custom.readVeja detalhes sobre as definições de objetos personalizados no CRM da HubSpot.Pontos de extremidade de objetos personalizadosQualquer Enterprise
crm.schemas.deals.readVeja detalhes sobre as configurações de propriedade dos negócios.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.deals.writeCrie, exclua ou altere as configurações de propriedades dos negócios.Pontos de extremidade de propriedadesQualquer conta
crm.schemas.line_items.readVeja detalhes sobre itens de linha.Pontos de extremidade de itens de linhaQualquer conta
crm.schemas.quotes.readVeja detalhes sobre orçamentos e modelos de orçamento.Pontos de extremidade de orçamentosQualquer conta
settings.billing.writeFaç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çõesQualquer conta
settings.currencies.readLê as taxas de câmbio existentes, juntamente com a moeda atual da empresa associada ao seu portal.Pontos de extremidade de informações da contaQualquer conta
settings.currencies.writeCrie, 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 contaQualquer conta
settings.users.readVeja detalhes sobre os usuários da conta e suas permissões.Pontos de extremidade de provisionamento de usuáriosQualquer conta
settings.users.writeGerencie 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áriosQualquer conta
settings.users.teams.readVeja detalhes sobre as equipes da conta.Pontos de extremidade de provisionamento de usuáriosQualquer conta
settings.users.team.writeAtribua usuários a equipes em sua conta da HubSpot.Pontos de extremidade de provisionamento de usuáriosQualquer conta
account-info.security.readInclui acesso a registros de atividade da conta e outras informações de segurança da conta.API de atividade da contaQualquer conta
accountingPermite que a HubSpot e a integração contábil compartilhem detalhes de faturas, produtos e contatos.API de extensão de contabilidadeQualquer conta
actionsAdicione formulários às páginas do contato que realizam ações personalizadas.API de extensões do CRMQualquer contato
analytics.behavioral_events.sendInclui acesso para enviar eventos comportamentais personalizados.API de análisesMarketing Hub Enterprise
automationIsso 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_writeCrie, leia, atualize ou exclua eventos comportamentais. Inclui propriedades de eventos comportamentais.API de análisesMarketing Hub Enterprise
business_units.view.readVeja dados da unidade de negócios, incluindo as informações de logotipo.API de unidades de negóciosComplemento de Unidades de negócios
business-intelligenceInclui pontos de extremidade que estão na parte superior de origens e e-mails.API de análiseQualquer conta
collector.graphql_query.executeConsulte dados da sua conta da HubSpot usando o ponto de extremidade da API do GraphQLPonto de extremidade da API do GraphQLCMS Hub Professional ou Enterprise
collector.graphql_schema.readRealize consultas de introspecção por meio de clientes de aplicativos GraphQL, como GraphiQLGraphiQL e outros clientes GraphQL de terceirosCMS Hub Professional ou Enterprise
communication_preferences.readVeja detalhes das preferências de assinatura de seus contatos.API de preferências de assinaturaQualquer conta
communication_preferences.read_writeAssine/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 assinaturaQualquer conta
communication_preferences.writeAssine/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 assinaturaQualquer conta
contentInclui sites, landing pages, e-mail, blog e campanhas.API do CMS e pontos de extremidade de calendário, e-mail e eventos de e-mailCMS Hub Professional ou Enterprise, ou Marketing Hub Professional ou Enterprise
conversations.readVeja detalhes sobre os threads na caixa de entrada de conversas.API de mensagens e caixa de entrada de ConversasQualquer 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 visitanteQualquer Professional ou Enterprise
conversations.writeEnvie mensagens em conversas. Crie e atualize threads de mensagens.API de mensagens e caixa de entrada de conversasQualquer conta
crm.exportExporte registos do seu CRM para todos os tipos de dados de CRM.API de exportações do CRMQualquer conta
crm.importPermite 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 CRMQualquer conta
ctas.readPermite acesso de leitura para CTAs.Nenhuma publicAPI disponívelMarketing Hub ou CMS Hub Starter, Professional ou Enterprise
e-commerceInclui acesso aos recursos de e-commerce.Pontos de extremidade de produtos e itens de linhaQualquer conta
external_integrations.forms.accessInclui a capacidade de renomear, excluir e clonar formulários existentes.Pontos de extremidade de formuláriosQualquer conta
filesIsso 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.readVeja 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
formsInclui acesso aos pontos de extremidade de formulários.Pontos de extremidade de provisionamento de formuláriosQualquer conta
forms-uploaded-filesBaixe arquivos enviados por meio de um formulário.Obter um arquivo carregado por meio de um ponto de extremidade de envio de formulárioQualquer conta
hubdbIsso inclui acesso ao HubDB.Pontos de extremidade HubDBCMS Hub Professional ou Enterprise ou Marketing Hub Professional ou Enterprise com o Complemento de site
integration-syncExibe a API de sincronização, que permite sincronizar a maioria dos objetos do CRM.API de ponte de comércio eletrônicoQualquer conta
media_bridge.readConcede acesso a eventos e objetos do media bridge.API de Media BridgeQualquer conta
media_bridge.writeConcede acesso para criar e atualizar eventos e objetos do media bridge.API de Media BridgeQualquer conta
oauthEscopo básico obrigatório para OAuth. Este escopo é adicionado por padrão a todos os aplicativos.Qualquer conta
sales-email-readConcede 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
socialInclui a caixa de entrada social.API de mídia socialMarketing Hub Professional ou Enterprise
ticketsInclui acesso a tickets.Pontos de extremidade de ticketsQualquer conta
timelineConcede 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 tempoQualquer conta
transactional-emailInclui 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