Migrer vers des jetons avec périmètre

Les jetons hérités désignent les jetons créés avant le lancement des jetons à portée limitée d’impact.com en juin 2025. Si vous utilisez actuellement des jetons hérités pour vous authentifier auprès des API d’impact.com, il est temps de passer aux jetons à portée limitée.

Les jetons hérités accordent un large accès à toutes les API destinées aux clients, ce qui présente des risques importants en matière de sécurité et d’exploitation. Les jetons à portée limitée offrent une alternative plus sûre et plus facile à gérer. En savoir plus sur Bonnes pratiques pour les jetons à portée limitée.

Étapes de migration

1. Évaluez vos intégrations actuelles

Commencez par identifier toutes les intégrations existantes (applications, scripts ou services) qui utilisent un jeton hérité. Avant de créer de nouveaux jetons, vous devez comprendre ce qui pourrait changer lorsque vous passez à une version plus récente de l’API.

Commencez par répertorier chaque intégration et noter sa fonction, les points de terminaison spécifiques auxquels elle accède, les types d’actions qu’elle effectue (lecture, écriture ou les deux), ainsi que la personne qui en est propriétaire ou qui la maintient.

Portez une attention particulière aux changements incompatibles entre versions de l’API. Vous devriez :

• Examinez vos charges utiles de requête, car les nouvelles versions peuvent renommer des champs, modifier des types de données ou exiger de nouveaux champs. Des structures de données non correspondantes sont une cause fréquente d’erreurs d’exécution.

• Examinez la structure des charges utiles de réponse, car des champs peuvent être renommés, supprimés ou imbriqués différemment, ce qui nécessitera des mises à jour de la logique de votre application pour la lecture des réponses de l’API.

2. Générez un nouveau jeton à portée limitée

Une fois votre évaluation terminée, vous pouvez générer un nouveau jeton à portée limitée. Consultez notre guide de création de jetons à portée limitée, que vous soyez un la marque, partenaire, ou agence.

Sur la base de votre évaluation, dressez la liste de tous les points de terminaison utilisés par votre intégration et faites correspondre chaque opération, comme GET, POST, PUT, ou DELETE à sa portée minimale correspondante dans la nouvelle version de l’API. Lorsque vous créez le jeton, vous n’attribuerez que ces portées granulaires, en l’adaptant aux besoins spécifiques de l’intégration.

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

Enfin, donnez au jeton 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é les nouveaux identifiants.

3. Testez votre intégration

Avant la mise en production, vous devez tester minutieusement l’intégration mise à jour dans un environnement de préproduction ou de développement. Mettez temporairement à jour le code de votre intégration dans cet environnement de test pour utiliser le nouveau jeton à portée limitée 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 portées du nouveau jeton. Vous devriez recevoir une erreur 403 Interdit qui confirme que le jeton restreint correctement l’accès. Après avoir corrigé tout code en fonction de votre évaluation d’impact, comme la mise à jour de la logique de requête/réponse ou des noms de champs, effectuez de nouveaux tests 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 changements dans votre environnement de production. Implémentez toutes les modifications de code et mises à jour de configuration validées dans votre base de code de production.

L’étape la plus importante ici consiste à remplacer l’ancien jeton hérité par le nouveau jeton à portée limitée. Une fois le nouveau jeton actif, surveillez de près l’intégration et les journaux de l’application afin de 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 définitivement ou de supprimer l’ancien jeton hérité inutilisé. C’est une étape de sécurité cruciale, car un jeton hérité compromis avec des autorisations étendues représente un risque important.

Pour terminer le processus, mettez à jour votre documentation interne et informez les membres concernés de l’équipe au sujet du nouveau jeton. Veillez à documenter la manière dont il est géré afin d’éviter toute utilisation abusive et d’assurer une maintenance fluide à l’avenir.