Migrate an API key integration to a private app

Si ves un banner en tu cuenta sobre cómo desactivar tu clave de API:

  • Las claves API para desarrolladores son independientes de las claves de API estándar de HubSpot y no están obsoletas. Las claves de la API de desarrollador se utilizan para administrar la configuración relacionada con tus aplicaciones de HubSpot, incluidas las suscripciones a la API de webhooks y los tipos de eventos de la API de eventos de línea de tiempo.

Si has creado una integración interna que utiliza una clave de API de HubSpot, tu clave de API proporciona acceso de lectura y escritura a todos tus datos de CRM, lo que puede ser un riesgo de seguridad si tu clave de API está comprometida. Al migrar a una aplicación privada, puedes autorizar los alcances específicos que requiere tu integración, lo que genera un token de acceso que limita los datos que tu integración puede solicitar o cambiar en tu cuenta.

Sigue los pasos a continuación para migrar una integración de clave de API existente a una aplicación privada. Se recomienda usar primero un entorno de prueba, como una cuenta de prueba de desarrollador o una cuenta de entorno de pruebas, antes de realizar cambios en la producción. Si tienes preguntas durante la migración de tu aplicación, visita la Comunidad de desarrolladores

Para obtener una explicación del video de la migración de una integración de clave de API a una aplicación privada, echa un vistazo al video de Desarrolladores de HubSpot a continuación:

En esta guía

Nota: las aplicaciones privadas no admiten webhooks ni ciertos tipos de extensiones. Si tu integración existente utiliza cualquiera de estas características, deberías crear una aplicación pública usando OAuth en su lugar.

Crea una nueva aplicación privada

  • En tu cuenta de HubSpot, haz clic en el ícono de configuración en la barra de navegación principal.
  • En el menú de la barra lateral izquierda, navega a Integraciones > Aplicaciones privadas.
  • Haz clic en Crear página privada.
  • En la ficha Información básica, configura los detalles de tu aplicación:
    • Introduce el Nombre de tu aplicación.
    • Coloca el cursor sobre el logotipo del parámetro de sustitución y haz clic en cargar icono para cargar una imagen cuadrada que funcionará como logotipo de tu aplicación.
    • Introduce una descripción para tu aplicación.
  • Haz clic en la pestaña Alcances.
  • A continuación, selecciona los alcances que deseas autorizar en función de las API que utiliza tu integración. Para averiguar qué alcances necesitará tu aplicación:
    • Compila una lista de API de HubSpot que utiliza tu integración existente.
    • Para cada solicitud de API, navega a la documentación de desarrollador asociada (por ejemplo, la API de contactos).
    • Haz clic en la pestaña Puntos de terminación y desplázate hasta el punto de terminación que utiliza tu integración.
    • En la sección Requisitos, busca los alcances necesarios para usar el extremo. Siempre que sea posible, deberías optar por los alcances enumerados en Alcances granulares en lugar de los que figuran en Alcances estándar. Si no se enumeran alcances granulares, usa los alcances estándar.locate-scope-in-endpoints-tab-for-private-app-migration
    • De nuevo en la configuración de tu aplicación privada, selecciona las casillas de comprobación Leer o Escribir junto a los alcances coincidentes. También puedes buscar un alcance usando la barra de búsqueda Buscar un alcance.select-matching-scope-for-private-app
  • Cuando hayas terminado de seleccionar tus alcances, haz clic en Crear aplicación en la parte superior derecha. Siempre puedes hacer cambios en tu aplicación después de crearla.
  • En el cuadro de diálogo, revisa la información sobre el token de acceso de la aplicación y haz clic en Continuar creando.

Con tu aplicación privada creada, puedes comenzar a hacer solicitudes de API usando su token de acceso. En la pestaña Detalles de la página de configuración de tu aplicación privada, haz clic en Mostrar token debajo de tu token de acceso para revelarlo.

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

Actualizar el método de autorización de las solicitudes de API de tu integración

En lugar de usar un parámetro de consulta hapiKey para realizar solicitudes de API, los tokens de acceso a aplicaciones privadas se incluyen en el encabezado Authorization de su solicitud. Al realizar una solicitud, establece el valor del encabezado Authorization en Bearer YOUR_ACCESS_TOKEN. A menos que se indique lo contrario, este método de autorización es compatible con todos los puntos de terminación de API públicos, incluidas las API heredadas que se enumeran en la documentación de desarrollador heredada de HubSpot.

Tu solicitud puede parecerse a lo siguiente:

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)

Los tokens de acceso privado se implementan en la parte superior de OAuth, de manera que también puedas hacer llamadas autenticadas con tu token de acceso utilizando una de las bibliotecas de clientes de HubSpot. Por ejemplo, si estás utilizando la biblioteca de cliente Node.js, puedes crear instancias de un cliente de OAuth al pasar el token de acceso de tu aplicación. 

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 completar la migración a tu aplicación privada, elimina todas las referencias a la clave de API de HubSpot de tu código y, en su lugar, utiliza el enfoque anterior para usar el token de acceso de tu aplicación privada. Dependiendo de la solicitud que estés haciendo, es posible que desees crear un secreto para almacenar tu token, en lugar de codificarlo en tus solicitudes. Usar un secreto evitará que tu token sea expuesto, como cuando usas un token en una función sin servidor. Para almacenar el token de acceso como secreto:

  • En la terminal, ejecuta hs secrets add secretName. Se recomienda asignar un nombre simple al secreto para que puedas hacer referencia fácilmente a él en el futuro.
  • Pega el token de acceso en el terminal y luego presiona Intro.

Luego puedes acceder a tu secreto como una variable de entorno. Más información en el ejemplo de funciones sin servidor a continuación.

Para confirmar que se han eliminado todas las referencias a tu clave de API, puedes comprobar el registro de llamadas en tu cuenta de HubSpot:

  • En tu cuenta de HubSpot, haz clic en el símbolo de configuración en la barra de navegación principal.
  • En la barra lateral izquierda, navega a Integraciones > Clave de API.
  • Revisa las solicitudes más recientes en la pestaña Registro de llamadas para confirmar que no se han realizado solicitudes recientes desde que se eliminaron todas las referencias anteriores para usar el token de acceso de la aplicación privada.

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

Si tienes una cuenta de Marketing Hub de pago con contactos de marketing, y previamente estableciste contactos creados por integraciones usando tu clave de API como contactos de marketing, también debes hacer lo mismo con tu aplicación privada:

  • En tu cuenta de HubSpot, haz clic en el ícono de configuración en la barra de navegación principal.
  • En la barra lateral izquierda, navega a Integraciones > Contactos de marketing.
  • En Tus aplicaciones conectadas, usa la barra de búsqueda para localizar tu aplicación privada y luego haz clic en Activar para sincronizar contactos como contactos de marketing.

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

Una vez que hayas terminado de configurar tu aplicación privada y confirmado que todas las referencias a tu clave de API se han eliminado en tu código, puedes desactivar la clave.

Verificar las solicitudes y monitorizar los registros

Una vez que hayas eliminado todas las referencias a la clave API de HubSpot en tu código y las hayas reemplazado con referencias al token de acceso de tu aplicación privada, no se requieren más cambios de código.

Si has seguido los pasos anteriores en una cuenta de prueba de desarrollador o sandbox, repite el mismo proceso en tu cuenta de producción. Luego, monitorea los registros de llamadas a la API de la aplicación privada y confirma que ninguna de las solicitudes de la aplicación devuelve 400 errores:

  • En tu cuenta de HubSpot, haz clic en el ícono de configuración en la barra de navegación principal.
  • En el menú de la barra lateral izquierda, navega a Integraciones > Aplicaciones privadas.
  • Haz clic en el nombre de tu aplicación privada.
  • Haz clic en la pestaña Registros.
  • Cualquier solicitud de API no satisfactoria, que falle debido a un alcance faltante, aparecerá como un error 403. Si accedes a los registros de tiempo de ejecución de tu integración, la respuesta de la solicitud de API correspondiente debe incluir un mensaje de error con detalles sobre los alcances que faltan.

403-error-after-private-app-migration

  • Si necesitas incluir un nuevo alcance para tu aplicación privada:
    • Haz clic en la pestaña Detalles.
    • Haz clic en Editar detalles.
    • En la parte superior de la página, haz clic en Alcances.
    • Selecciona la casilla de comprobación junto a cualquier alcance que falte y luego haz clic en Confirmar cambios en la parte superior derecha cuando hayas terminado.

select-missing-scopes-private-app-migration

Más información sobre cómo crear y administrar aplicaciones privadas, junto con sus límites, en la guía de aplicaciones privadas.

Ejemplos de implementación

A continuación, descubre más información sobre los usos comunes de las claves de API y cómo migrar a tokens de acceso a aplicaciones privadas.

Funciones sin servidor

Si usas una clave de API dentro de una función sin servidor, también puedes usar el token de acceso de la aplicación privada para la autenticación. Deberás asegurarte de que la aplicación privada tenga los alcances que la función necesita para ejecutarse. 

Para autenticar una función sin servidor con un token de acceso privado a la aplicación:

  • En la tarjeta de tokende acceso, haz clic en Mostrar token para mostrar tu token de acceso. A continuación, haz clic en Copiar para copiar el token al portapapeles.
    show-private-app-access-token-1
  • Con el token de acceso copiado, crea un nuevo secreto para almacenar el token:
    • En la terminal, ejecuta hs secrets add secretName. Se recomienda asignar un nombre simple al secreto para que puedas hacer referencia fácilmente a él en el futuro.
    • Pega el token de acceso en el terminal y luego presiona Intro.
  • En el archivo serverless.json de tu función sin servidor, agrega el nombre secreto a la matriz secrets:
// example serverless.json file { "runtime": "nodejs18.x", "version": "1.0", "secrets": ["secretName"], "endpoints": { "getPrompts": { "method": "GET", "file": "serverlessFunction.js" } } }
  • En el archivo JavaScript de la función sin servidor, establece el valor del encabezado Authorization en Bearer secretName. Por ejemplo, si estás llamando a la  API de contactos usando Node.js y axios, la solicitud será similar a lo siguiente:
// 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}); };

Trabajos de una sola vez

Si usas una clave de API para ejecutar trabajos únicos, como crear una propiedad, puedes crear una aplicación privada y usar su token de acceso para autenticar la llamada. Una vez que se crea una aplicación privada, puedes reutilizar su token de acceso para cualquier trabajo único, siempre y cuando la aplicación privada tenga los alcances adecuados. Puedes actualizar los alcances de una aplicación privada en cualquier momento desde la configuración de la aplicación privada en HubSpot. O bien, puedes eliminar la aplicación privada y crear una nueva específica para el trabajo que necesitas ejecutar.

private-app-edit-scopes

Crear objetos personalizados

En lugar de usar una clave API para crear un objeto personalizado, puedes crear una aplicación privada y usar su token de acceso para autenticar la llamada, siempre y cuando la aplicación tenga los alcances necesarios. Por ejemplo, al usar Postman para crear un objeto personalizado, establece el tipo de autorización en Token del portador y luego ingresa el token en el campo Token.

postman-private-app-access-token-field

Más información sobre cómo crear un objeto personalizado usando una aplicación privada en el blog de desarrolladores de HubSpot.

Acciones de workflow de código personalizado

Si estás usando una clave API en una acción de workflow de código personalizado, puedes usar el token de acceso de la aplicación privada, siempre que la aplicación tenga los alcances necesarios. Para realizar la actualización, abre la acción personalizada en el editor de workflows y, a continuación, realiza las siguientes actualizaciones:

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

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.