Migrar una integración de clave API a una aplicación privada

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.

Además, aunque las claves de API requieren actualización de tokens, los tokens de acceso a aplicaciones privadas no. Por lo tanto, no tendrás que incluir la actualización de tokens como parte de tu aplicación.

Sigue los pasos a continuación para migrar una integración de clave de API existente a una aplicación privada. Se recomienda utilizar 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.

En esta guía

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

Crear 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, utiliza 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 empezar a hacer solicitudes de API usando tu 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 su integración

En lugar de utilizar un parámetro de consulta hapiKey para realizar solicitudes de API, los tokens de acceso a aplicaciones privadas se incluyen en el encabezado Autorización de su solicitud. Al realizar una solicitud, establece el valor del encabezado Authorization en Bearer YOUR_ACCESS_TOKEN.

Por ejemplo, si estás haciendo una llamada a la API de contactos usando Node.js y la biblioteca de axios, tu solicitud se parecería 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 } );

Los tokens de acceso privado se implementan en la parte superior de OAuth, de manera que también podrás 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 });

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-migrationUna vez que hayas 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 insuficiente, aparecerá como un error 403. Si accede a los registros de tiempo de ejecución de su 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 aplicació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": "nodejs12.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

 

Acciones de flujo de trabajo 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 flujos de trabajo y, a continuación, realiza las siguientes actualizaciones:

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