Migra a tokens con ámbito

Los tokens heredados se refieren a los tokens creados antes del lanzamiento de los tokens con alcance de impact.com en junio de 2025. Si actualmente usas tokens heredados para autenticarte con las API de impact.com, es hora de hacer la transición a tokens con alcance.

Los tokens heredados otorgan amplio acceso a través de todas las API orientadas al cliente, lo que presenta importantes riesgos de seguridad y operativos. Los tokens con alcance ofrecen una alternativa más segura y manejable. Lee más sobre Mejores prácticas para tokens con alcance.

Pasos de migración

1. Evalúa tus integraciones actuales

Primero, identifica todas las integraciones existentes (aplicaciones, scripts o servicios) que usan un token heredado. Antes de crear nuevos tokens, debes entender qué podría cambiar cuando cambies a una versión más reciente de la API.

Empieza por enumerar cada integración y registrar su función, los endpoints específicos a los que accede, los tipos de acciones que realiza (lectura, escritura o ambas) y quién es el propietario o mantiene la integración.

Presta mucha atención a cualquier cambio incompatibile entre versiones de la API. Debes:

• Revisa las cargas útiles de tus solicitudes, ya que las nuevas versiones pueden cambiar el nombre de campos, modificar tipos de datos o requerir nuevos campos. Las estructuras de datos incompatibles son una fuente común de errores en tiempo de ejecución.

• Examina la estructura de las cargas útiles de respuesta, ya que los campos pueden cambiar de nombre, eliminarse o anidarse de forma diferente, lo que requerirá actualizaciones en la lógica de tu aplicación para leer las respuestas de la API.

2. Genera un nuevo token con alcance

Una vez completada tu evaluación, puedes generar un nuevo token con alcance. Usa nuestra guía para crear tokens con alcance, ya seas un marca, partner, o agencia.

Según tu evaluación, enumera cada endpoint que usa tu integración y asigna cada operación como GET, POST, PUT, o DELETE a su alcance mínimo correspondiente en la nueva versión de la API. Cuando crees el token, asignarás solo estos alcances granulares, adaptándolo a las necesidades específicas de la integración.

Selecciona la versión de la API de destino al generar el token, ya que esto determina el comportamiento y las estructuras de datos que autorizará. Para minimizar las interrupciones, podrías empezar por coincidir con la versión que ya usa tu integración y planear una actualización aparte más adelante.

Por último, asigna al token un nombre descriptivo que indique su propósito y la versión de la API (por ejemplo, Reporting_v2_Read-Only) y guarda de forma segura las nuevas credenciales.

3. Prueba tu integración

Antes de ponerlo en producción, debes probar a fondo la integración actualizada en un entorno de pruebas o desarrollo. Actualiza temporalmente el código de tu integración en este entorno de pruebas para usar el nuevo token con alcance y la nueva URL base de la API. Ejecuta todos los flujos de trabajo principales para verificar que las lecturas, creaciones, actualizaciones y eliminaciones de datos funcionen como se espera.

Como parte de tus pruebas de seguridad, intenta acceder a un endpoint que no esté cubierto por los alcances del nuevo token. Deberías recibir un 403 Forbidden error, lo que confirma que el token está restringiendo el acceso correctamente. Después de corregir cualquier código según tu evaluación de impacto, como actualizar la lógica de solicitud/respuesta o los nombres de los campos, vuelve a probar e itera hasta que todas las funciones trabajen correctamente.

4. Actualiza tu integración

Después de realizar pruebas exitosas, estás listo para implementar los cambios en tu entorno de producción. Implementa todos los cambios de código y actualizaciones de configuración validados en tu base de código de producción.

El paso más importante aquí es reemplazar el antiguo token heredado por el nuevo token con alcance. Una vez que el nuevo token esté activo, supervisa de cerca la integración y los registros de la aplicación para asegurarte de que no se produzcan errores inesperados.

5. Comunica el cambio

Después de confirmar que tu nueva integración funciona sin problemas, es hora de revocar o eliminar de forma permanente el token heredado antiguo y no utilizado. Este es un paso de seguridad crucial, ya que un token heredado comprometido con permisos amplios supone un riesgo significativo.

Para cerrar el proceso, actualiza tu documentación interna e informa a los miembros relevantes del equipo sobre el nuevo token. Asegúrate de documentar cómo se gestiona para evitar el uso indebido y garantizar un mantenimiento fluido en el futuro.