Migrare ai token con ambito

I token legacy si riferiscono ai token creati prima del lancio dei token con ambito (scoped tokens) di impact.com nel giugno 2025. Se attualmente usi 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 rischi significativi di sicurezza e operativi. I token con ambito offrono un'alternativa più sicura e gestibile. Leggi di più su Linee guida per i token con ambito.

Passaggi per la 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 comprendere cosa potrebbe cambiare quando passi a una versione più recente 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 possiede o mantiene l'integrazione.

Presta particolare attenzione a eventuali modifiche incompatibili tra versioni dell'API. Dovresti:

• Rivedere i payload delle richieste, poiché le nuove versioni potrebbero rinominare campi, modificare i tipi di dati o richiedere nuovi campi. Strutture di dati non corrispondenti sono una fonte comune di errori a runtime.

• Esaminare 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 valutazione, puoi generare un nuovo token con ambito. Usa la nostra guida per creare token con ambito, sia che tu sia un marchio, partner, o agenzia.

In base alla tua valutazione, elenca ogni endpoint che la tua integrazione utilizza e mappa ogni operazione come GET, POST, PUT, o 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 target dell'API durante la generazione del token, poiché questo determina il comportamento e le strutture dei dati che autorizzerà. Per ridurre al minimo le interruzioni, potresti iniziare abbinando la versione che la tua integrazione già utilizza e pianificare un aggiornamento separato in seguito.

Infine, assegna al token un nome descrittivo che indichi il suo scopo e la versione dell'API (es. Reporting_v2_Read-Only) e conserva 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 usare il nuovo token con ambito e il nuovo URL base dell'API. Esegui tutti i flussi di lavoro principali per verificare che letture, creazioni, aggiornamenti e cancellazioni dei dati funzionino come previsto.

Come parte dei test di sicurezza, prova ad accedere a un endpoint non coperto dagli ambiti del nuovo token. Dovresti ricevere un errore 403 Forbidden , che conferma che il token sta limitando correttamente l'accesso. Dopo aver corretto qualsiasi codice in base alla tua valutazione dell'impatto, come aggiornare la logica di richiesta/risposta o i nomi dei campi, riesegui i test e iterare fino a quando tutte le funzioni funzionano correttamente.

4. Aggiorna la tua integrazione

Dopo test riusciti, sei pronto a distribuire le modifiche nell'ambiente di produzione. Implementa tutte le modifiche di codice validate e gli aggiornamenti di configurazione nel codice 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 nuova integrazione funziona correttamente, è il momento di revocare o eliminare permanentemente il vecchio token legacy inutilizzato. Questo è un passaggio cruciale per la sicurezza, poiché un token legacy compromesso con ampie autorizzazioni rappresenta un rischio significativo.

Per completare il processo, aggiorna la documentazione interna e informa i membri del team interessati sul nuovo token. Assicurati di documentarne la gestione per prevenire usi impropri e garantire una manutenzione agevole in futuro.