Guide Technique : Migration de OAuth 1 vers OAuth V2

Action requise : Tous les endpoints dans le code source doivent être mis à jour. Il est recommandé d’utiliser des variables d’environnement ou une procédure globale de "rechercher et remplacer" afin de refléter le changement de TLD de .it vers .com.

3. Évolution de la gestion des tokens

3.1 Cartographie des endpoints

La V2 adopte une nomenclature RESTful au pluriel pour la gestion des ressources de tokens. L’endpoint des opérations sur les tokens passe ainsi de /token à /tokens.

3.2 Création et paramètres (TokenCreate)

Dans la V2, l’endpoint POST /tokens étend le contrôle granulaire au-delà des simples champs scopes et ttl. Les paramètres suivants, définis dans le schéma TokenCreate, sont désormais pris en charge : name (identifiant mnémotechnique pour les logs d’audit), limit_total (plafond total de requêtes), limit_paid (limite maximale de requêtes payantes), ips (liste blanche d’adresses IP autorisées) et wallet_limit (budget spécifique alloué depuis le Wallet global).

3.3 Mise à jour et flux de refresh token

Alors qu’en V1 la méthode PATCH était limitée à la modification partielle des métadonnées, en V2 la méthode PATCH /tokens/{token} est standardisée pour prendre en charge le flux de rotation (refresh token). Cela permet de faire tourner les identifiants et de mettre à jour les permissions sans invalider l’identifiant existant, garantissant ainsi la continuité opérationnelle et une sécurité renforcée.

3.4 Comparaison de la structure JSON

La V2 retourne l’objet TokenDetail (partie du schéma TokenListOrDetail), intégrant des limites et métadonnées auparavant indisponibles.

Réponse OAuth 1 (Legacy) :

{
  "scopes": ["POST:valutometro.altravia.com/valutazione"],
  "expire": 1634223407,
  "token": "5f8711afe4754a532a7a8358",
  "success": true,
  "message": "",
  "error": null
}

Réponse OAuth V2 (TokenDetail) :

{
  "name": "Production_Token_01",
  "token": "6f9822bgf5862b643b8b9469",
  "expire": 1735689600,
  "scopes": [
    {
      "domain": "imprese.openapi.it",
      "endpoint": "base",
      "method": "GET"
    }
  ],
  "limits": {
    "limit_total": 1000,
    "limit_paid": 500,
    "wallet_limit": 50.00
  },
  "ips": ["192.168.1.1"],
  "success": true
}

4. Du crédit (V1) au Wallet (V2)

La V2 introduit la gestion financière via le module Wallet, garantissant la transparence des transactions. La consultation du solde se fait désormais via GET /wallet, remplaçant l’ancien /credit. La traçabilité des transactions est assurée par GET /wallet/transactions, qui permet d’accéder à l’historique des opérations. Contrairement à la valeur statique de la V1, l’historique en V2 est paginé, permettant une analyse détaillée pour les comptes à fort volume transactionnel.

5. Systèmes de monitoring : des compteurs aux statistiques avancées

Le système /counters de la V1, basé sur des agrégations temporelles rigides, est remplacé par le moteur multidimensionnel /stats. La granularité de la V2 permet des agrégations par token, IP, domaine et scope. Les appels tels que GET /stats/ips identifient les adresses IP uniques, GET /stats/apis agrège la consommation par domaine API, et GET /stats/apis/{domain} fournit la répartition exacte des scopes utilisés dans un domaine spécifique. Des journaux intégrés sont également disponibles pour la visibilité des erreurs via /errors.

6. Nouvelles fonctionnalités exclusives d’OAuth V2

La version 2.0.0 introduit des endpoints de monitoring auparavant inexistants :

• Callbacks (/callbacks) : Endpoint pour surveiller et vérifier le statut de livraison des callbacks générés par les API.
• Subscriptions (/subscriptions) : Gestion et inspection des abonnements actifs associés au compte.
• Error Logs (/errors) : Accès programmatique aux logs d’erreurs (ErrorLog), essentiels pour le débogage en temps réel des intégrations.

7. Tableau de référence rapide pour les développeurs