# Auf Bereichsgefilterte 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 umzusteigen.

Legacy-Tokens gewähren umfangreichen Zugriff auf alle kundenorientierten APIs, 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](https://help.impact.com/other/de/reference-documentation/api-access-tokens-and-changelog/scoped-tokens-best-practices).

#### Migrationsschritte

<details>

<summary>1. Bewerten Sie Ihre aktuellen Integrationen</summary>

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

Beginnen Sie damit, jede Integration aufzulisten und deren Funktion, die spezifischen Endpunkte, auf die sie zugreift, die Arten von Aktionen, die sie ausführt (lesen, schreiben oder beides), sowie den Eigentümer oder die verantwortliche Person zu dokumentieren.

Achten Sie genau auf alle Breaking Changes zwischen [API-Versionen](https://help.impact.com/other/de/reference-documentation/api-access-tokens-and-changelog/api-changelog-summary). Sie sollten:

* Überprüfen Sie Ihre Request-Payloads, da neue Versionen Felder umbenennen, Datentypen ändern oder neue Felder verlangen können. Nicht passende 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 Anpassungen an der Logik Ihrer Anwendung zum Lesen von API-Antworten erforderlich macht.

</details>

<details>

<summary>2. Erstellen Sie ein neues Scoped Token</summary>

Sobald Ihre Bewertung abgeschlossen ist, können Sie ein neues Scoped Token erstellen. Nutzen Sie unseren Leitfaden zum Erstellen von Scoped Tokens, unabhängig davon, ob Sie ein [Marke](https://app.gitbook.com/s/wMLlMoFBtKJa8ptd3zaw/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand), [Partner](https://app.gitbook.com/s/b2rE79d9UhOKZQLgzSqx/account-management/account-settings/api-tokens/create-an-api-access-token-as-a-partner), oder [Agentur](https://app.gitbook.com/s/okTNfAIjBtFchXJ9pC2q/account-settings/api-tokens/create-api-access-tokens-as-an-agency).

Basierend auf Ihrer Bewertung listen Sie jeden Endpunkt auf, den Ihre Integration verwendet, und ordnen jede Operation wie `GET`, `POST`, `PUT`, oder `DELETE` dem jeweils entsprechenden minimalen Scope in der neuen API-Version zu. Beim Erstellen des Tokens weisen Sie nur diese granularen Scopes zu und passen es an die spezifischen Bedürfnisse der Integration an.

Wählen Sie beim Generieren des Tokens die Ziel-API-Version aus, da diese das Verhalten und die Datenstrukturen bestimmt, die das Token autorisieren wird. Um Unterbrechungen zu minimieren, können 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 beschreibenden Namen, der seinen Zweck und die API-Version angibt (z. B. Reporting\_v2\_Read-Only), und speichern Sie die neuen Anmeldeinformationen sicher.

</details>

<details>

<summary>3. Testen Sie Ihre Integration</summary>

Bevor Sie live gehen, sollten Sie die aktualisierte Integration gründlich in einer Staging- oder Entwicklungsumgebung testen. Aktualisieren Sie vorübergehend den Code Ihrer Integration in dieser Testumgebung, um das neue Scoped Token und die neue API-Basis-URL zu verwenden. Führen Sie alle Hauptabläufe aus, um zu überprüfen, dass Datenlese-, Erstellungs-, Aktualisierungs- und Löschvorgänge wie erwartet funktionieren.

Im Rahmen Ihrer Sicherheitstests versuchen Sie, auf einen Endpunkt zuzugreifen, der nicht durch die Scopes des neuen Tokens abgedeckt ist. Sie sollten einen `403 Forbidden` Fehler erhalten, der bestätigt, dass das Token den Zugriff korrekt einschränkt. Nachdem Sie basierend auf Ihrer Auswirkungsbewertung etwaige Codeänderungen vorgenommen haben, wie die Aktualisierung der Request-/Response-Logik oder von Feldnamen, testen Sie erneut und iterieren, bis alle Funktionen korrekt arbeiten.

</details>

<details>

<summary>4. Aktualisieren Sie Ihre Integration</summary>

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

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

</details>

<details>

<summary>5. Kommunizieren Sie die Änderung</summary>

Nachdem Sie bestätigt haben, dass Ihre neue Integration reibungslos läuft, ist es an der Zeit, das alte, nicht mehr verwendete Legacy-Token dauerhaft zu widerrufen oder zu löschen. Dies ist ein entscheidender Sicherheitschritt, da ein kompromittiertes Legacy-Token mit weitreichenden Berechtigungen ein erhebliches Risiko darstellt.

Zum Abschluss des Prozesses aktualisieren Sie Ihre interne Dokumentation und informieren Sie die relevanten Teammitglieder über das neue Token. Dokumentieren Sie unbedingt, wie es verwaltet wird, um Missbrauch zu verhindern und eine reibungslose Wartung in der Zukunft zu gewährleisten.

</details>
