Zu Scoped Tokens migrieren

Legacy-Tokens beziehen sich auf Tokens, die vor der Einführung der Scoped Tokens von impact.com im Juni 2025 erstellt wurden. Wenn Sie derzeit Legacy-Tokens zur Authentifizierung bei den impact.com-APIs verwenden, ist es an der Zeit, auf Scoped Tokens umzustellen.

Legacy-Tokens gewähren weitreichenden Zugriff über alle kundenorientierten APIs hinweg, was erhebliche Sicherheits- und Betriebsrisiken mit sich bringt. Scoped Tokens bieten eine sicherere und besser verwaltbare Alternative. Lesen Sie mehr über Best Practices für Scoped Tokens.

Migrationsschritte

1. Bewerten Sie Ihre aktuellen Integrationen

Identifizieren Sie zunächst alle vorhandenen Integrationen (Apps, Skripte oder Dienste), die einen Legacy-Token verwenden. Bevor Sie neue Tokens erstellen, sollten Sie verstehen, was sich ändern könnte, wenn Sie auf eine neuere API-Version umsteigen.

Beginnen Sie damit, jede Integration aufzulisten und ihre Funktion, die spezifischen Endpunkte, auf die sie zugreift, die Arten von Aktionen, die sie ausführt (Lesen, Schreiben oder beides), sowie die Person, die für die Integration verantwortlich ist oder sie verwaltet, zu erfassen.

Achten Sie besonders auf etwaige Breaking Changes zwischen API-Versionen. Sie sollten:

• Überprüfen Sie Ihre Request-Payloads, da neue Versionen Felder umbenennen, Datentypen ändern oder neue Felder erfordern können. Nicht übereinstimmende Datenstrukturen sind eine häufige Ursache für Laufzeitfehler.
• Untersuchen Sie die Struktur der Response-Payloads, da Felder umbenannt, entfernt oder anders verschachtelt sein können, was Aktualisierungen der Logik Ihrer Anwendung zum Lesen von API-Antworten erforderlich macht.

2. Generieren Sie einen neuen Scoped Token

Sobald Ihre Bewertung abgeschlossen ist, können Sie einen neuen Scoped Token generieren. Verwenden Sie unseren Leitfaden zum Erstellen von Scoped Tokens, unabhängig davon, ob Sie ein Marke, trägt der Partner, oder Agentur.

Basierend auf Ihrer Bewertung listen Sie jeden Endpunkt auf, den Ihre Integration verwendet, und ordnen Sie jede Operation wie GET, POST, PUT, oder DELETE dem entsprechenden minimalen Scope in der neuen API-Version zu. Wenn Sie den Token erstellen, weisen Sie nur diese granularen Scopes zu und passen ihn an die spezifischen Anforderungen der Integration an.

Wählen Sie bei der Generierung des Tokens die Ziel-API-Version aus, da diese das Verhalten und die Datenstrukturen bestimmt, die autorisiert werden. Um Störungen zu minimieren, könnten Sie zunächst die Version wählen, die Ihre Integration bereits verwendet, und ein separates Upgrade später planen.

Geben Sie dem Token schließlich einen aussagekräftigen Namen, der seinen Zweck und die API-Version angibt (z. B. Reporting_v2_Read-Only), und speichern Sie die neuen Zugangsdaten sicher.

3. Testen Sie Ihre Integration

Bevor Sie live gehen, sollten Sie die aktualisierte Integration in einer Staging- oder Entwicklungsumgebung gründlich testen. Aktualisieren Sie den Code Ihrer Integration in dieser Testumgebung vorübergehend, um den neuen Scoped Token und die neue API-Basis-URL zu verwenden. Führen Sie alle primären Workflows aus, um zu überprüfen, ob das Lesen, Erstellen, Aktualisieren und Löschen von Daten wie erwartet funktioniert.

Versuchen Sie im Rahmen Ihrer Sicherheitstests, auf einen Endpunkt zuzugreifen, der nicht durch die Scopes des neuen Tokens abgedeckt ist. Sie sollten einen 403 Forbidden Fehler erhalten, was bestätigt, dass der Token den Zugriff korrekt einschränkt. Nachdem Sie etwaige Codeanpassungen auf Grundlage Ihrer Auswirkungsanalyse vorgenommen haben, wie z. B. die Aktualisierung der Request-/Response-Logik oder der Feldnamen, testen Sie erneut und iterieren Sie, bis alle Funktionen korrekt funktionieren.

4. Aktualisieren Sie Ihre Integration

Nach erfolgreichem Testen sind Sie bereit, die Änderungen in Ihrer Produktionsumgebung bereitzustellen. Implementieren Sie alle validierten Codeänderungen und Konfigurationsaktualisierungen in Ihrer Produktionscodebasis.

Der wichtigste Schritt hierbei ist, den alten Legacy-Token durch den neuen Scoped Token zu ersetzen. Sobald der neue Token aktiv ist, überwachen Sie die Integration und die Anwendungsprotokolle genau, um sicherzustellen, dass keine unerwarteten Fehler auftreten.

5. Kommunizieren Sie die Änderung

Nachdem Sie bestätigt haben, dass Ihre neue Integration reibungslos läuft, ist es an der Zeit, den alten, ungenutzten Legacy-Token dauerhaft zu widerrufen oder zu löschen. Dies ist ein entscheidender Sicherheitsschritt, da ein kompromittierter Legacy-Token mit weitreichenden Berechtigungen ein erhebliches Risiko darstellt.

Um den Prozess abzuschließen, aktualisieren Sie Ihre interne Dokumentation und informieren Sie relevante Teammitglieder über den neuen Token. Stellen Sie sicher, dass Sie dokumentieren, wie er verwaltet wird, um Missbrauch zu verhindern und eine reibungslose Wartung in Zukunft zu gewährleisten.