Technischer Leitfaden: Migration von OAuth 1 zu OAuth V2

Erforderliche Maßnahme: Alle Endpoint-Verweise im Quellcode müssen aktualisiert werden. Es wird empfohlen, Umgebungsvariablen oder eine globale „Suchen-und-Ersetzen“-Prozedur zu verwenden, um die Änderung der TLD von .it zu .com abzubilden.

3. Entwicklung des Token-Managements

3.1 Endpoint-Mapping

V2 führt eine pluralisierte RESTful-Namenskonvention für die Verwaltung von Token-Ressourcen ein. Der Endpoint für Token-Operationen wird von /token auf /tokens geändert.

3.2 Erstellung und Parameter (TokenCreate)

In V2 erweitert der POST /tokens-Endpoint die granulare Steuerung über die einfachen Felder scopes und ttl hinaus. Unterstützt werden nun die folgenden im TokenCreate-Schema definierten Parameter: name (mnemonischer Identifier für Audit-Logs), limit_total (maximales Anfragevolumen), limit_paid (maximales Volumen kostenpflichtiger Anfragen), ips (Whitelist autorisierter IP-Adressen) und wallet_limit (aus dem globalen Wallet zugewiesenes Budget).

3.3 Update und Refresh-Token-Flow

Während in V1 die PATCH-Methode auf partielle Metadatenänderungen beschränkt war, ist in V2 die Methode PATCH /tokens/{token} standardisiert, um den Token-Rotations- bzw. Refresh-Flow zu unterstützen. Dadurch können Zugangsdaten rotiert und Berechtigungen aktualisiert werden, ohne den bestehenden Identifier zu invalidieren, was die Betriebskontinuität und Sicherheit gewährleistet.

3.4 Vergleich der JSON-Struktur

V2 gibt das Objekt TokenDetail (Teil des TokenListOrDetail-Schemas) zurück und integriert Limits sowie Metadaten, die zuvor nicht verfügbar waren.

OAuth 1 Antwort (Legacy):

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

OAuth V2 Antwort (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. Vom Credit (V1) zum Wallet (V2)

V2 führt das Finanzmanagement über das Wallet-Modul ein und sorgt für vollständige Transparenz der Transaktionen. Die Abfrage des Kontostands erfolgt nun über GET /wallet und ersetzt das frühere /credit. Die Nachverfolgbarkeit von Transaktionen wird durch GET /wallet/transactions gewährleistet, das Zugriff auf die Transaktionshistorie bietet. Im Gegensatz zum statischen Wert in V1 ist die Historie in V2 paginierbar, was detaillierte Analysen für Konten mit hohem Transaktionsvolumen ermöglicht.

5. Monitoring-Systeme: Von Counters zu erweiterten Statistiken

Das V1-System /counters, das auf starren zeitlichen Aggregationen basierte, wird durch die multidimensionale /stats-Engine ersetzt. Die Granularität von V2 ermöglicht Aggregationen nach Token, IP, Domain und Scope. Aufrufe wie GET /stats/ips identifizieren eindeutige IP-Adressen, GET /stats/apis aggregiert die Nutzung nach API-Domain und GET /stats/apis/{domain} liefert die genaue Aufschlüsselung der innerhalb einer bestimmten Domain verwendeten Scopes. Zusätzlich stehen integrierte Logs zur Fehleranalyse über /errors zur Verfügung.

6. Neue exklusive Funktionen von OAuth V2

Version 2.0.0 führt zuvor nicht vorhandene Monitoring-Endpunkte ein:

• Callbacks (/callbacks): Endpoint zur Überwachung und Überprüfung des Zustellstatus von API-Callbacks.
• Subscriptions (/subscriptions): Verwaltung und Einsicht aktiver Abonnements, die dem Account zugeordnet sind.
• Error Logs (/errors): Programmatischer Zugriff auf Fehlerprotokolle (ErrorLog), essenziell für das Echtzeit-Debugging von Integrationen.

7. Schnelle Referenztabelle für Entwickler