il blog delle automazioni

GoHighLevel API key v1: migrare ai Private Integrations senza fermare Zapier o Make

Sommario

La gohighlevel api key v1 non è più supportata: cosa significa in pratica

Dal 31 dicembre 2025, GoHighLevel ha smesso di mantenere l’API v1 e la sua chiave di autenticazione. Le automazioni che la usano possono continuare a girare, ma qualsiasi problema non verrà corretto. Nessun bug fix, nessun aggiornamento di sicurezza, nessuna garanzia di compatibilità futura con gli endpoint.

«Continua a funzionare» non vuol dire «va bene lasciarlo così». Un sistema che gira su un’infrastruttura non mantenuta è una macchina che si rompe in silenzio: produce output, non si lamenta, e il giorno in cui smette di farlo non trovi un log che ti dica perché.

Il sostituto sono i Private Integrations di GoHighLevel, con token a permessi granulari. Questa guida copre il censimento delle connessioni attive, la creazione dei token, il test parallelo e lo spegnimento controllato delle vecchie chiavi. Non tocchi nulla di attivo finché il nuovo non ha già girato.

Scrivania con due monitor e foglio di censimento delle integrazioni GoHighLevel attive

Prima di muovere un file: il censimento

Ogni strumento che si connette a GoHighLevel tramite API key v1 è un nodo da tracciare. Zapier, Make, n8n, moduli custom, webhook diretti: tutti.

Apri ogni piattaforma e cerca le connessioni etichettate LeadConnector o GoHighLevel. In Zapier trovi le app connesse sotto My Apps. In Make le connessioni sono sotto Connections. In n8n le credenziali sono sotto Credentials. Annota per ciascuna: quale strumento usa la chiave, quali Zap o scenari la usano, quale sub-account o agenzia serve.

Il risultato deve essere una lista, anche un foglio con tre colonne: strumento, numero di automazioni attive che lo usano, sub-account collegato. Senza questa lista stai operando a occhi chiusi.

Una regola che vale sempre quando si gestisce questo tipo di infrastruttura: un token per strumento, non uno condiviso. Se ruoti o revochi un token, vuoi colpire una sola integrazione, non tutte insieme.

Creare un Private Integration token in GoHighLevel

I Private Integrations sono disponibili sia a livello agenzia sia a livello sub-account. Vai dove serve in base a cosa stai sostituendo.

Il percorso è: Settings → Private Integrations → Create New Integration. Dai un nome che identifichi lo strumento (Zapier – Sub-account X, non token1). Aggiungi una descrizione che dica cosa fa. Poi scegli i permessi.

La scelta degli scope: meno è meglio

GoHighLevel ti mostra un elenco di scope per risorsa: contatti, opportunità, appuntamenti, conversazioni e così via. Abilita solo quelli che l’integrazione usa davvero. Se Zapier legge i contatti e crea opportunità, non abilitare la gestione dei workflow o delle fatture.

Permessi troppo ampi non fanno girare meglio l’integrazione: aumentano la superficie di danno se il token viene compromesso o usato per sbaglio in uno scenario che non doveva toccare quei dati.

Il token si vede una volta sola

Dopo la creazione, GoHighLevel mostra il token una volta. Copialo subito in un posto sicuro — un password manager, non un foglio Google condiviso. Se lo perdi devi generarne uno nuovo e aggiornare tutte le connessioni che lo usavano.

La regola

Un token per strumento, non uno condiviso

Se revochi un token vuoi colpire una sola integrazione. Con un token condiviso tra Zapier e Make, ruotarlo significa aggiornare entrambi nello stesso momento sotto pressione.

  • Token separati per strumento — un token per Zapier, uno per Make, uno per n8n
  • Nomi descrittivi — il nome deve dire strumento e sub-account, non essere generico
  • Copia immediata — il token si vede una volta sola dopo la creazione

Autenticare le nuove connessioni su Zapier, Make e n8n

Il token va passato nell’header HTTP come Authorization: Bearer <token>. Non è una semplice sostituzione della chiave v1 nello stesso campo: il meccanismo di autenticazione è diverso e, in alcuni strumenti, devi creare una nuova connessione da zero invece di modificare quella esistente.

Zapier

In Zapier, GoHighLevel espone le sue azioni tramite l’app LeadConnector. Se la connessione esistente usa la vecchia chiave, crea una nuova connessione con il token Private Integration e usa quella negli Zap nuovi. Non modificare gli Zap attivi: duplicali, cambia la connessione nel duplicato, testalo.

Make

In Make, crea una nuova connessione sotto Connections con il token come Bearer. I moduli che usano la vecchia connessione continuano a girare finché non li aggiorni esplicitamente. Costruisci gli scenari nuovi con la connessione nuova, eseguili in parallelo, verifica i risultati prima di disattivare i vecchi.

n8n

In n8n le credenziali GoHighLevel di tipo API Key vanno sostituite con credenziali di tipo Header Auth o con il tipo nativo che accetta Bearer token, a seconda della versione che stai usando. Crea le credenziali nuove, aggiornale nei nodi del workflow duplicato, non in quello attivo.

Schema a mano di test parallelo tra vecchia API key e nuovo Private Integration token

Confronto tra API key v1 e Private Integration token

Prima di procedere con il test, è utile avere chiaro cosa cambia tra i due sistemi di autenticazione.

Caratteristica API key v1 Private Integration token
Supporto attivo Terminato il 31/12/2025 Sì, in sviluppo attivo
Meccanismo auth Chiave in header proprietario Bearer token (Authorization header)
Permessi granulari No Sì, per scope e risorsa
Rotazione consigliata n.d. Ogni 90 giorni
Token visibile dopo la creazione Sempre Una volta sola
Compatibilità endpoint Endpoint v1 Endpoint v2/v3 (verificare per ogni endpoint)

La trappola più comune: non è solo un cambio di autenticazione

Questo è il punto che fa più danni. Chi migra pensando che basti sostituire la chiave con il token scopre che alcune richieste cambiano struttura e alcune risposte cambiano formato. Un campo che prima si chiamava contact_id in un endpoint v1 potrebbe chiamarsi id in v2, o essere annidato diversamente nel JSON di risposta.

Non promettere a te stesso compatibilità degli endpoint. Ogni integrazione che sostituisci va testata con una chiamata reale — un lead di prova, un’opportunità di test — e il risultato va confrontato con quello che produceva prima.

L’altro punto critico è l’header Version. Alcuni endpoint GoHighLevel richiedono Version: 2021-07-28 o la versione corretta per la chiamata che stai facendo. Se lo ometti, la risposta può essere un errore generico che non ti dice nulla di utile. Controlla la documentazione API ufficiale di GoHighLevel per ogni endpoint che usi.

Permessi insufficienti producono un 401 o un 403 che almeno è esplicito. Ma scope configurati male su risorse adiacenti possono far passare la chiamata e restituire un dato vuoto o parziale: l’automazione gira, non segnala errori, e lavora su dati incompleti. Per chi vuole capire come costruire workflow GoHighLevel robusti con le guardie giuste, questo articolo sul trigger che scarta contatti senza dirlo è un buon punto di partenza.

Il metodo per automatizzare un’agenzia senza bloccare la produzione

La regola è una: non modificare mai un’automazione attiva che porta soldi. Costruisci accanto, prova, poi spegni.

Il processo concreto è questo:

  1. Duplica lo Zap, lo scenario o il workflow che usa la vecchia chiave.
  2. Nel duplicato, sostituisci la connessione con quella che usa il nuovo token Private Integration.
  3. Aggiorna gli endpoint se necessario, controlla il formato delle richieste e delle risposte.
  4. Esegui il duplicato con un lead o un contatto di test: verifica che i dati arrivino dove devono.
  5. Fai girare il duplicato in parallelo al vecchio per almeno 24-48 ore su traffico reale.
  6. Se tutto quadra, spegni il vecchio e cancellalo.
  7. Revoca la vecchia API key v1 solo dopo aver confermato che non ci sono altre integrazioni che la usano.

Per chi gestisce più sub-account — il caso tipico di chi sta automatizzando un’agenzia con GoHighLevel — questo processo va ripetuto per ogni sub-account separatamente. I token Private Integration a livello sub-account non ereditano i permessi dell’agenzia.

GoHighLevel

Prova GoHighLevel con i Private Integrations già attivi

Nei primi 14 giorni puoi costruire le connessioni nuove accanto a quelle esistenti senza toccare la produzione.

  • Giorno 1-2 — crea i Private Integrations e copia i token subito
  • Giorno 3-5 — duplica le automazioni attive e collegale ai nuovi token
  • Giorno 6-14 — test parallelo su traffico reale e poi spegnimento controllato delle vecchie chiavi

Attiva la prova di 14 giorni →

Link di affiliazione: se ti iscrivi da qui io prendo una commissione, tu paghi uguale. Lo linko perché ci lavoro dentro ogni giorno.

La rotazione dei token dopo la migrazione

La documentazione GoHighLevel raccomanda di ruotare i Private Integration token ogni 90 giorni. In fase di rotazione, il vecchio e il nuovo token restano entrambi attivi per 7 giorni: questo è il margine per aggiornare tutte le connessioni senza fermare nulla.

Metti un promemoria nel calendario. Non è una raccomandazione decorativa: un token che non viene mai ruotato è un vettore di rischio che cresce nel tempo. Se stai gestendo più sub-account per più clienti, la rotazione è una procedura che va documentata e assegnata, non ricordata a memoria.

Sul fronte dei tool di automazione, la scelta tra Zapier, Make e n8n cambia il modo in cui gestisci le credenziali e la logica di test. Se stai valutando quale strumento usare come spina dorsale delle tue automazioni, il confronto tra n8n e Zapier copre le differenze strutturali che contano per chi gestisce volumi seri.

L’API v1 di GoHighLevel era una chiave globale senza granularità. I Private Integrations sono più lavoro da configurare e da mantenere. Sono anche l’unico sistema su cui puoi costruire qualcosa di controllabile: sai esattamente cosa può fare ogni token, quando è stato creato e quando va ruotato. Un sistema senza queste informazioni non è finito — gira e basta, finché non smette.

Domande frequenti

Posso usare lo stesso Private Integration token per Zapier e Make insieme?

No. Usa un token separato per ogni strumento. Se devi revocare o ruotare un token, vuoi aggiornare una sola piattaforma per volta. Con un token condiviso, qualsiasi intervento tocca entrambe le integrazioni nello stesso momento.

Le automazioni con la vecchia API key v1 smettono di funzionare subito?

Non necessariamente subito. Dal 31/12/2025 GoHighLevel ha smesso di mantenere l’API v1: le integrazioni esistenti possono ancora girare, ma non ricevono bug fix né aggiornamenti. Il rischio cresce nel tempo, non è immediato.

Dove trovo i Private Integrations in GoHighLevel?

Nel pannello di GoHighLevel vai su Settings, poi Private Integrations. Da lì puoi creare una nuova integrazione, assegnarle un nome, scegliere gli scope e generare il token. Il percorso è lo stesso sia a livello agenzia sia a livello sub-account.

Cosa succede se configuro gli scope sbagliati nel Private Integration?

Scope insufficienti producono un errore 401 o 403, che almeno è visibile. Scope mal configurati su risorse adiacenti possono far passare la chiamata e restituire dati vuoti o parziali: l’automazione gira senza errori e lavora su informazioni incomplete. Verifica sempre con una chiamata di test su dati reali.

Trasparenza: in questo articolo c’è un link di affiliazione. Se ti iscrivi da lì io ricevo una commissione, per te non cambia niente. Linko solo strumenti che uso in produzione.

Iscriviti GRATIS a Gohighlevel

Il miglior software per scalare il tuo business. Se mi contatti dopo la prova gratuita dimostrando che ti sei iscritto con il mio link, hai una consulenza gratuita.

Hai domande?

Ogni tuo dubbio è un’opportunità per me di aiutarti.

Angelo Marcoccia

CHI SONO

Ho passato gli ultimi anni a costruire i sistemi che hanno portato un business da zero a oltre un milione di euro al mese — acquisizione, vendita, delivery e dati, tutto automatizzato. Oggi progetto gli stessi sistemi per infobusiness e agenzie che vogliono crescere senza esplodere di operatività. Quello che consiglio, lo so costruire con le mie mani.

INIZIA A CAPIRCI QUALCOSA

Mettiamoci in contatto

LEGGI IL BLOG SUlle automazioni

AUTOMATIZzA IL TUO BUSINESS