Migrate an API key integration to a private app

Caso veja um banner na sua conta sobre como desativar a chave de API:

  • As chaves de API de desenvolvedor são separadas das chaves de API padrão da HubSpot e não serão descontinuadas. As chaves de API de desenvolvedor são utilizadas para gerenciar as configurações relacionadas aos seus aplicativos HubSpot, incluindo assinaturas da API de webhooks e tipos de eventos da API de eventos de linha do tempo.

Se você criou uma integração interna que usa umachave de API da HubSpot, sua chave de API fornecerá acesso de leitura e gravação a todos os seus dados de CRM da HubSpot, o que poderá representar um risco de segurança se sua chave de API for comprometida. Ao migrar para um aplicativo privado, você pode autorizar os escopos específicos exigidos pela sua integração, o que gerará um token de acesso para limitar os dados que a integração pode solicitar ou alterar em sua conta.

Siga as etapas abaixo para migrar uma integração de chave de API existente para um aplicativo privado. É recomendado usar um ambiente de testes primeiro, como uma conta de teste de desenvolvedor ou uma conta de sandbox, antes de colocar as alterações em produção. Se você tiver dúvidas durante a migração do aplicativo, acesse a Comunidade de desenvolvedores

Para obter um vídeo passo a passo da migração de uma integração de chave de API para um aplicativo privado, confira o vídeo para Desenvolvedores da HubSpot abaixo:

Neste guia

Observação: os aplicativos privados não são compatíveis com webhooks e alguns tipos de extensões. Se sua integração existente usar um desses recursos, você deverá criar um aplicativo público usando OAuth.

Criar um novo aplicativo privado

  • Na sua conta da HubSpot, clique no ícone de configurações na barra de navegação principal.
  • No menu lateral esquerdo, acesse Integrações > Aplicativos privados.
  • Clique em Criar aplicativo privado.
  • Na guia Informações básicas, configure os detalhes do aplicativo:
    • Insira o nome do aplicativo.
    • Passe o cursor do mouse sobre o logotipo de espaço reservado e clique no ícone de upload para carregar uma imagem quadrada que servirá como logotipo do seu aplicativo.
    • Insira uma descrição para o aplicativo.
  • Clique na guia Escopos.
  • Em seguida, selecione os escopos para autorizar com base nas APIs usadas pela integração. Para descobrir quais escopos o aplicativo precisará:
    • Crie uma lista das APIs da HubSpot usadas pela sua integração existente.
    • Para cada solicitação de API, acesse a documentação do desenvolvedor associada (por exemplo, a API de contatos).
    • Clique na guia Endpoints e role até o endpoint usado pela integração.
    • Na seção Requisitos, localize os escopos necessários para usar o endpoint. Sempre que possível, opte pelos escopos listados em Escopos granulares em vez de usar os Escopos padrão. Se nenhum escopo granular estiver listado, use os escopos padrão.locate-scope-in-endpoints-tab-for-private-app-migration
    • Nas configurações do aplicativo privado, marque as caixas de seleção Leitura ou Gravação ao lado dos escopos correspondentes. Você também pode pesquisar um escopo usando a barra de pesquisa Localizar um escopo.select-matching-scope-for-private-app
  • Depois de selecionar seus escopos, clique em Criar aplicativo no canto superior direito. Você pode fazer alterações no seu aplicativo depois de criá-lo.
  • Na caixa de diálogo, revise as informações sobre o token de acesso do aplicativo e clique em Continuar criando.

Com seu aplicativo privado criado, você pode começar a fazer solicitações de API usando seu token de acesso. Na guia Detalhes da página de configurações do seu aplicativo privado, clique em Mostrar token abaixo do token de acesso para revelá-lo.

show-private-app-access-token-migration-guide

Atualizar o método de autorização das solicitações de API da sua integração

Em vez de usar um parâmetro de consulta hapiKey para fazer solicitações de API, os tokens de acesso para aplicativos privados são incluídos no cabeçalho Authorization da solicitação. Ao fazer uma solicitação, defina o valor do cabeçalho Authorization como Bearer YOUR_ACCESS_TOKEN. Salvo indicação em contrário, este método de autorização é compatível com todos os endpoints da API pública, incluindo as APIs antigas listadas na antiga documentação do desenvolvedor da HubSpot.

O seu pedido pode assemelhar-se ao seguinte:

axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );$headers = [ 'Content-Type: application/json', 'Authorization: Bearer ' . YOUR_ACCESS_TOKEN, ]; $curl = curl_init(); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); curl_setopt($curl, CURLOPT_URL, 'https://api.hubapi.com/crm/v3/objects/contacts'); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $contacts = curl_exec($curl); curl_close($curl); var_dump($contacts);require 'uri' require 'net/http' require 'openssl' url = URI("https://api.hubapi.com/crm/v3/objects/contacts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(url) request['content-type'] = 'application/json' token = 'YOUR_ACCESS_TOKEN' request['authorization'] = "Bearer #{token}" response = http.request(request) puts response.read_bodyimport requests url = "https://api.hubapi.com/crm/v3/objects/contacts" headers = { 'content-type': 'application/json', 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } response = requests.request("GET", url, headers=headers) print(response.text)

Os tokens de acesso para aplicativos privados são implementados na OAuth, para que você também possa fazer chamadas autenticadas usando uma das bibliotecas de cliente do HubSpot. Por exemplo, se você estiver usando a biblioteca de cliente Node.js, poderá iniciar um cliente OAuth enviando o token de acesso do seu aplicativo. 

const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN }); $hubSpot = \HubSpot\Factory::createWithAccessToken('access-token'); $response = $hubSpot->crm()->contacts()->basicApi()->getPage();# Load the gem require 'hubspot-api-client' # Setup client client = Hubspot::Client.new(access_token: 'YOUR_ACCESS_TOKEN') # Get contacts contacts = client.crm.contacts.basic_api.get_pagefrom hubspot import HubSpot api_client = HubSpot(access_token='YOUR_ACCESS_TOKEN') api_client.crm.contacts.get_page()

Para concluir a migração para o seu aplicativo privado, remova todas as referências à chave de API da HubSpot do seu código e, em vez disso, use a abordagem acima para usar o token de acesso do seu aplicativo privado. Dependendo da solicitação que está fazendo, você pode querer criar um segredo para armazenar seu token, em vez de codificá-lo em suas solicitações. O uso de um segredo impedirá que o token seja exposto, como ao usar um token em uma função sem servidor. Para armazenar o token de acesso como um segredo:

  • No terminal, execute hs secrets add secretName. É recomendado dar um nome simples ao segredo para que você possa referenciá-lo com facilidade no futuro.
  • Cole o token de acesso no terminal e pressione Enter.

Você pode acessar seu segredo como uma variável de ambiente. Saiba mais no exemplo de funções sem servidor abaixo.

Para confirmar que todas as referências à sua chave de API foram removidas, você pode verificar o registro de chamadas na sua conta da HubSpot:

  • Na sua conta da HubSpot, clique no ícone de configurações na barra de navegação principal.
  • Na barra lateral esquerda, acesse Integrações > Chave de API.
  • Revise as solicitações mais recentes na guia Registro de chamadas para confirmar que nenhuma solicitação recente foi feita desde a remoção de todas as referências anteriores para usar o token de acesso do seu aplicativo privado.

check-api-key-call-log-after-migration

Se você tiver uma conta paga do Marketing Hub com contatos de marketing e definir contatos criados por integrações usando sua chave de API como contatos de marketing, também deverá fazer o mesmo com seu aplicativo privado:

  • Na sua conta da HubSpot, clique no ícone de configurações na barra de navegação principal.
  • Na barra lateral esquerda, acesse Integrações > Contatos de marketing.
  • Em Seus aplicativos conectados, utilize a barra de pesquisa para localizar o aplicativo privado e, em seguida, clique para ativar a opção Ative para sincronizar como contatos de marketing.

set-private-app-contacts-as-marketing-contacts

Quando terminar de configurar seu aplicativo privado e confirmar que todas as referências à sua chave de API foram removidas do código, você poderá desativá-la.

Verificar solicitações e monitorar registros

Depois de remover todas as referências à chave de API da HubSpot em seu código e substituí-las por referências ao token de acesso do seu aplicativo privado, nenhuma outra alteração de código será necessária.

Se você seguiu as etapas acima em uma conta de teste ou sandbox de desenvolvedor, repita o mesmo processo na sua conta de produção. Em seguida, monitore os registros das chamadas de API do aplicativo privado e confirme se nenhuma das solicitações do aplicativo retorna erros 400:

  • Na sua conta da HubSpot, clique no ícone de configurações na barra de navegação principal.
  • No menu lateral esquerdo, acesse Integrações > Aplicativos privados.
  • Clique no nome do aplicativo privado.
  • Clique na guia Registros.
  • Qualquer solicitação de API com falha devido a um escopo ausente aparecerá como um erro 403. Se você acessar os registros de tempo de execução da sua integração, a resposta da solicitação de API correspondente deverá incluir uma mensagem de erro com detalhes sobre quaisquer escopos ausentes.

403-error-after-private-app-migration

  • Se você precisar incluir um novo escopo para seu aplicativo privado:
    • Clique na guia Detalhes.
    • Clique em Editar detalhes.
    • No canto superior da página, clique em Escopos.
    • Marque a caixa de seleção ao lado dos escopos ausentes e clique em Confirmar alterações no canto superior direito quando terminar.

select-missing-scopes-private-app-migration

Saiba mais sobre como criar e gerenciar aplicativos privados, bem como seus limites, no guia de aplicativos privados.

Exemplos de implementação

Abaixo, saiba mais sobre os usos comuns das chaves de API e como migrar para tokens de acesso para aplicativos privados.

Funções sem servidor

Se você estiver usando uma chave de API dentro de uma função sem servidor, poderá usar o token de acesso para aplicativo privado na autenticação. Será necessário garantir que o aplicativo privado tenha os escopos que a função precisa executar. 

Para autenticar uma função sem servidor com um token de acesso para aplicativo privado:

  • No cartão Token de acesso, clique em Mostrar token para revelar seu token de acesso. Em seguida, clique em Copiar para copiar o token para a área de transferência.
    show-private-app-access-token-1
  • Com o token de acesso copiado, crie um novo segredo para armazenar o token:
    • No terminal, execute hs secrets add secretName. É recomendado dar um nome simples ao segredo para que você possa referenciá-lo com facilidade no futuro.
    • Cole o token de acesso no terminal e pressione Enter.
  • No arquivo serverless.json da sua função sem servidor, adicione o nome secreto à matriz secrets:
// example serverless.json file { "runtime": "nodejs18.x", "version": "1.0", "secrets": ["secretName"], "endpoints": { "getPrompts": { "method": "GET", "file": "serverlessFunction.js" } } }
  • No arquivo JavaScript da sua função sem servidor, defina o valor do cabeçalho Authorization como Bearer secretName. Por exemplo, se você estiver fazendo uma chamada para a API de contatos usando Node.js e axios, a solicitação terá a seguinte aparência:
// example serverless function const axios = require('axios'); exports.main = (context, sendResponse) => { axios.get(`https://api.hubapi.com/crm/v3/objects/contacts`, { headers: { 'Authorization': `Bearer ${process.env.secretName}`, 'Content-Type': 'application/json' } } ) sendResponse({statusCode: 200}); };

Trabalhos únicos

Se você estiver usando uma chave de API para executar trabalhos únicos, como criar uma propriedade, poderá criar um aplicativo privado e usar seu token de acesso para autenticar a chamada. Assim que um aplicativo privado for criado, você poderá reutilizar seu token de acesso para qualquer trabalho único, desde que o aplicativo privado tenha os escopos adequados. Você pode atualizar os escopos de um aplicativo privado a qualquer momento nas configurações do aplicativo privado no HubSpot. Ou, você pode excluir o aplicativo privado e criar um novo específico para o trabalho que precisa executar.

private-app-edit-scopes

Criar objetos personalizados

Em vez de usar uma chave de API para criar um objeto personalizado, você pode criar um aplicativo privado e usar seu token de acesso para autenticar a chamada, desde que o aplicativo tenha os escopos necessários. Por exemplo, ao usar Postman para criar um objeto personalizado, defina o tipo de autorização como Token do portador e insira o token no campo Token.

postman-private-app-access-token-field

Saiba mais sobre como criar um objeto personalizado usando um aplicativo privado no blog do desenvolvedor da HubSpot.

Ações de fluxo de trabalho de código personalizado

Se você estiver usando uma chave de API em uma ação de fluxo de trabalho de código personalizado, poderá usar o token de acesso do aplicativo privado, desde que o aplicativo tenha os escopos necessários. Para fazer a atualização, abra a ação personalizada no editor de fluxo de trabalho e faça as seguintes atualizações:

const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName });

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