Migra ai token con ambito

I token legacy si riferiscono ai token creati prima del lancio dei token con ambito di impact.com nel giugno 2025. Se attualmente utilizzi token legacy per autenticarti con le API di impact.com, è il momento di passare ai token con ambito.

I token legacy concedono un accesso ampio a tutte le API rivolte ai clienti, il che comporta significativi rischi per la sicurezza e operativi. I token con ambito offrono un'alternativa più sicura e gestibile. Leggi di più su Best practice per i token con ambito.

Passaggi di migrazione

1. Valuta le tue integrazioni attuali

Per prima cosa, identifica tutte le integrazioni esistenti (app, script o servizi) che utilizzano un token legacy. Prima di creare nuovi token, dovresti capire cosa potrebbe cambiare quando passi a una nuova versione dell'API.

Inizia elencando ogni integrazione e registrandone la funzione, gli endpoint specifici a cui accede, i tipi di azioni che esegue (lettura, scrittura o entrambe) e chi la possiede o la mantiene.

Presta molta attenzione a eventuali modifiche di rilievo tra versioni dell'API. Dovresti:

• Esamina i payload delle tue richieste, poiché le nuove versioni potrebbero rinominare i campi, modificare i tipi di dati o richiedere nuovi campi. Strutture di dati non corrispondenti sono una fonte comune di errori di runtime.
• Esamina la struttura dei payload di risposta, poiché i campi potrebbero essere rinominati, rimossi o annidati in modo diverso, il che richiederà aggiornamenti alla logica della tua applicazione per la lettura delle risposte API.

2. Genera un nuovo token con ambito

Una volta completata la tua analisi, puoi generare un nuovo token con ambito. Usa la nostra guida per creare token con ambito, sia che tu sia un brand, partner, oppure agenzia.

In base alla tua analisi, elenca ogni endpoint utilizzato dalla tua integrazione e mappa ogni operazione come GET, POST, PUT, oppure DELETE al corrispondente ambito minimo nella nuova versione dell'API. Quando crei il token, assegnerai solo questi ambiti granulari, adattandolo alle esigenze specifiche dell'integrazione.

Seleziona la versione API di destinazione quando generi il token, poiché questa determina il comportamento e le strutture dei dati che autorizzerà. Per ridurre al minimo le interruzioni, potresti iniziare facendo corrispondere la versione che la tua integrazione utilizza già e pianificare un aggiornamento separato in seguito.

Infine, dai al token un nome descrittivo che indichi il suo scopo e la versione API (ad es. Reporting_v2_Read-Only) e salva in modo sicuro le nuove credenziali.

3. Testa la tua integrazione

Prima di andare in produzione, dovresti testare a fondo l'integrazione aggiornata in un ambiente di staging o di sviluppo. Aggiorna temporaneamente il codice della tua integrazione in questo ambiente di test per utilizzare il nuovo token con ambito e il nuovo URL base dell'API. Esegui tutti i flussi di lavoro principali per verificare che le letture, le creazioni, gli aggiornamenti e le eliminazioni dei dati funzionino come previsto.

Come parte dei tuoi test di sicurezza, prova ad accedere a un endpoint non coperto dagli ambiti del nuovo token. Dovresti ricevere un 403 Forbidden errore, che conferma che il token sta limitando correttamente l'accesso. Dopo aver corretto eventuali problemi nel codice in base alla tua analisi dell'impatto, come l'aggiornamento della logica delle richieste/risposte o dei nomi dei campi, esegui nuovi test e itera fino a quando tutte le funzioni non funzionano correttamente.

4. Aggiorna la tua integrazione

Dopo aver completato con successo i test, sei pronto per distribuire le modifiche nel tuo ambiente di produzione. Implementa tutte le modifiche al codice e gli aggiornamenti di configurazione convalidati nella tua codebase di produzione.

Il passaggio più importante qui è sostituire il vecchio token legacy con il nuovo token con ambito. Una volta che il nuovo token è attivo, monitora attentamente i log dell'integrazione e dell'applicazione per assicurarti che non si verifichino errori imprevisti.

5. Comunica la modifica

Dopo aver confermato che la tua nuova integrazione funziona senza problemi, è il momento di revocare o eliminare in modo permanente il vecchio token legacy inutilizzato. Questo è un passaggio cruciale per la sicurezza, poiché un token legacy compromesso con autorizzazioni ampie rappresenta un rischio significativo.

Per concludere il processo, aggiorna la documentazione interna e informa i membri rilevanti del team sul nuovo token. Assicurati di documentare come viene gestito per prevenire usi impropri e garantire una manutenzione agevole in futuro.