Migrar a tokens con alcance

Los tokens heredados se refieren a los tokens creados antes del lanzamiento de los tokens con alcance (scoped tokens) de impact.com en junio de 2025. Si actualmente usas tokens heredados para autenticarte con las APIs de impact.com, es hora de migrar a tokens con alcance.

Los tokens heredados otorgan acceso amplio a todas las APIs orientadas al cliente, lo que presenta riesgos significativos 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 comprender qué podría cambiar cuando pases a una versión más nueva de la API.

Comienza enumerando cada integración y registrando su función, los endpoints específicos que accede, los tipos de acciones que realiza (lectura, escritura o ambas) y quién posee o mantiene la integración.

Presta especial atención a cualquier cambio incompatible entre versiones de la API. Debes:

• Revisar las cargas útiles (payloads) de tus solicitudes, ya que las nuevas versiones podrían renombrar campos, cambiar tipos de datos o requerir campos nuevos. Las estructuras de datos incompatibles son una fuente común de errores en tiempo de ejecución.

• Examinar la estructura de las respuestas, ya que los campos pueden ser renombrados, eliminados o anidados de manera 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 que tu evaluación esté completa, puedes generar un nuevo token con alcance. Usa nuestra guía para crear tokens con alcance, ya seas un marca, socio, o agencia.

Según tu evaluación, lista cada endpoint que tu integración utiliza y mapea 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 objetivo al generar el token, ya que esto dicta el comportamiento y las estructuras de datos que autorizará. Para minimizar la interrupción, podrías comenzar haciendo coincidir la versión que tu integración ya usa y planear una actualización separada más adelante.

Finalmente, dale 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 las nuevas credenciales de forma segura.

3. Prueba tu integración

Antes de ponerlo en producción, debes probar a fondo la integración actualizada en un entorno de staging o desarrollo. Actualiza temporalmente el código de tu integración en este entorno de prueba 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 según lo esperado.

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 campo, vuelve a probar e iterar hasta que todas las funciones funcionen correctamente.

4. Actualiza tu integración

Tras las pruebas exitosas, estarás listo para desplegar los cambios en tu entorno de producción. Implementa todos los cambios de código y las actualizaciones de configuración validadas en tu base de código de producción.

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

5. Comunica el cambio

Después de confirmar que tu nueva integración funciona correctamente, es hora de revocar o eliminar permanentemente el token heredado antiguo y no usado. Este es un paso de seguridad crucial, ya que un token heredado comprometido con permisos amplios representa un riesgo significativo.

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