Migrer vers des jetons à portée limitée

Les tokens hérités se réfèrent aux tokens créés avant le lancement des tokens à périmètre (scoped tokens) d'impact.com en juin 2025. Si vous utilisez actuellement des tokens hérités pour vous authentifier auprès des APIs d'impact.com, il est temps de passer aux tokens à périmètre.

Les tokens hérités accordent un accès étendu à l'ensemble des APIs orientées client, ce qui présente des risques importants pour la sécurité et l'exploitation. Les tokens à périmètre offrent une alternative plus sûre et plus facile à gérer. En savoir plus sur Bonnes pratiques des tokens à périmètre.

Étapes de migration

1. Évaluez vos intégrations actuelles

Commencez par identifier toutes les intégrations existantes (applications, scripts ou services) qui utilisent un token hérité. Avant de créer de nouveaux tokens, vous devez comprendre ce qui pourrait changer lorsque vous basculerez vers une version d'API plus récente.

Commencez par lister chaque intégration et notez sa fonction, les points de terminaison spécifiques auxquels elle accède, les types d'actions qu'elle effectue (lecture, écriture ou les deux) et qui possède ou maintient l'intégration.

Portez une attention particulière à tout changement incompatible entre versions d'API. Vous devriez :

• Passez en revue vos charges utiles de requête, car les nouvelles versions peuvent renommer des champs, modifier les types de données ou exiger de nouveaux champs. Les structures de données incompatibles sont une source fréquente d'erreurs d'exécution.

• Examinez la structure des réponses, car des champs peuvent être renommés, supprimés ou imbriqués différemment, ce qui exigera des mises à jour de la logique de votre application pour lire les réponses de l'API.

2. Générez un nouveau token à périmètre

Une fois votre évaluation terminée, vous pouvez générer un nouveau token à périmètre. Utilisez notre guide pour créer des tokens à périmètre, que vous soyez un marque, partenaire, ou agence.

Sur la base de votre évaluation, listez chaque point de terminaison utilisé par votre intégration et répertoriez chaque opération comme GET, POST, PUT, ou DELETE vers son périmètre minimal correspondant dans la nouvelle version de l'API. Lorsque vous créez le token, vous n'assignerez que ces périmètres granulaires, en l'adaptant aux besoins spécifiques de l'intégration.

Sélectionnez la version de l'API cible lors de la génération du token, car cela détermine le comportement et les structures de données qu'il autorisera. Pour minimiser les perturbations, vous pouvez commencer par correspondre à la version que votre intégration utilise déjà et planifier une mise à niveau distincte ultérieurement.

Enfin, donnez au token un nom descriptif qui indique son objectif et la version de l'API (par ex. Reporting_v2_Read-Only) et enregistrez en toute sécurité ces nouvelles informations d'identification.

3. Testez votre intégration

Avant la mise en production, vous devez tester minutieusement l'intégration mise à jour dans un environnement de mise en scène ou de développement. Mettez temporairement à jour le code de votre intégration dans cet environnement de test pour utiliser le nouveau token à périmètre et la nouvelle URL de base de l'API. Exécutez tous les flux de travail principaux pour vérifier que les lectures, créations, mises à jour et suppressions de données fonctionnent comme prévu.

Dans le cadre de vos tests de sécurité, essayez d'accéder à un point de terminaison qui n'est pas couvert par les périmètres du nouveau token. Vous devriez recevoir une 403 Forbidden erreur, ce qui confirme que le token restreint correctement l'accès. Après avoir corrigé tout code basé sur votre évaluation d'impact, comme la mise à jour de la logique de requête/réponse ou des noms de champs, retestez et itérez jusqu'à ce que toutes les fonctions fonctionnent correctement.

4. Mettez à jour votre intégration

Après des tests réussis, vous êtes prêt à déployer les modifications dans votre environnement de production. Implémentez tous les changements de code validés et les mises à jour de configuration dans votre base de code de production.

L'étape la plus importante ici est de remplacer l'ancien token hérité par le nouveau token à périmètre. Une fois le nouveau token actif, surveillez de près les journaux d'intégration et d'application pour vous assurer qu'aucune erreur inattendue ne se produit.

5. Communiquez le changement

Après avoir confirmé que votre nouvelle intégration fonctionne correctement, il est temps de révoquer ou de supprimer définitivement l'ancien token hérité inutilisé. Il s'agit d'une étape cruciale pour la sécurité, car un token hérité compromis avec des permissions étendues représente un risque important.

Pour clore le processus, mettez à jour votre documentation interne et informez les membres d'équipe concernés du nouveau token. Veillez à documenter la manière dont il est géré pour éviter les abus et assurer une maintenance fluide à l'avenir.