Torna alla documentazioneConnettori

Connettori personalizzati

Aggiungi un connettore personalizzato con una chiave API o una credenziale OAuth.

Ultimo aggiornamento 10 luglio 2026 · 6 min read

Il catalogo copre oltre 100 servizi, ma ogni team ha alcuni strumenti interni o prodotti SaaS regionali che non vi figurano. I connettori personalizzati risolvono questo problema.

Registri una credenziale — una chiave API o credenziali OAuth — e spieghi a Zero come chiamare il servizio. Da quel momento, Zero tratta il tuo connettore personalizzato in modo identico a uno integrato: stesso registro di audit, stesso proxy ad accesso mediato, stessi gate per le azioni sensibili.

Due varianti

Scegli il tipo che corrisponde al tuo servizio:

  • Chiave API — funziona per qualsiasi servizio che si autentica con un token statico in un header. Il percorso più semplice e veloce: incolli la chiave, dai un nome al connettore, indichi a Zero l'URL di base. La maggior parte delle API interne e molti strumenti SaaS usano questo metodo.
  • OAuth 2.0 — per i servizi che emettono token per singolo utente tramite OAuth. Fornisci un client ID e un secret, configuri gli scope che vuoi che Zero possa richiedere, e Zero esegue il flusso OAuth per ciascun utente quando necessario.

Se non sei sicuro di quale usare, controlla la documentazione API del servizio a monte. La dicitura "chiave API" (o "personal access token") di solito indica la variante 1; "OAuth" (o "client credentials") di solito indica la variante 2.

Configurare un connettore con chiave API

  1. Apri la pagina Connectors nel tuo workspace.
  2. Fai clic su Add custom connector → API key.
  3. Compila:
    • Name. Qualcosa che Zero possa riconoscere leggendo i prompt, es. internal-billing-api o acme-crm.
    • Base URL. La radice dell'API: https://api.internal.acme.com.
    • Auth header. Di solito Authorization: Bearer YOUR_TOKEN o X-API-Key: YOUR_TOKEN. Adatta a ciò che il servizio si aspetta.
    • API key. Incolla la credenziale. Memorizzata crittografata; mai visibile dopo il salvataggio.
    • Allowed paths (opzionale). Limita Zero a endpoint specifici, come /v1/invoices/*. Riduce il raggio d'azione.
  4. Fai clic su Save e Test connection. Zero interroga l'URL di base con un GET / (o un percorso che specifichi) e riporta la risposta.

Configurare un connettore OAuth 2.0

Un po' più di lavoro, ma vale la pena per i servizi in cui conta l'autorizzazione per singolo utente:

  1. Registra un'applicazione OAuth presso il servizio a monte. Otterrai un client ID e un client secret. Imposta il redirect URI su quello che VM0 mostra nel modulo di aggiunta connettore.
  2. In VM0: Add custom connector → OAuth 2.0.
  3. Compila:
    • Name e Base URL, come sopra
    • Authorization URL e Token URL dalla documentazione OAuth del servizio a monte
    • Client ID e Client secret
    • Scopes. L'elenco degli scope che Zero è autorizzato a richiedere. Usa il minimo che copra i tuoi flussi di lavoro.
  4. Salva. La prima sessione che necessita di questo connettore attiva il flusso OAuth per ciascun utente.

Spiegare a Zero come usare un connettore personalizzato

Due modi. Scegli quello che si adatta al tuo flusso di lavoro.

Descrivilo inline quando chiedi a Zero di fare qualcosa:

"Usa il connettore internal-billing-api per recuperare la fattura #4422. Poi invia il PDF via email a ops@acme.com."

Zero carica la specifica del connettore e individua quale endpoint chiamare. Questo funziona perché i connettori sono corredati di metadati in stile OpenAPI (rilevati automaticamente per molti servizi, opzionalmente forniti manualmente).

Scrivi una skill che faccia riferimento al connettore per nome. Il corpo della skill descrive la procedura; Zero carica la skill automaticamente quando la descrizione corrisponde a una richiesta in arrivo. Per i flussi di lavoro ripetuti, questo è più pulito che ridescrivere inline ogni volta.

Una skill chiamata pull-invoice con descrizione "recupera una fattura da internal-billing-api e invia il PDF via email" — una volta scritta, Zero la invoca ogni volta che qualcuno chiede una fattura.

Specifiche OpenAPI e schemi inline

Zero funziona al meglio con un connettore personalizzato quando conosce gli endpoint, i metodi e i parametri disponibili. Tre modi per fornirli:

  • Rilevamento automatico dal file /openapi.json o /swagger.json del servizio, se ne espone uno. Basta indicare a Zero l'URL.
  • Carica una specifica. Incolla o carica un OpenAPI 3 in YAML/JSON. Zero lo analizza e offre metadati in stile tooltip mentre costruisce le chiamate.
  • Descrizioni inline. Per gli strumenti interni senza specifiche, puoi scrivere una breve descrizione markdown nel corpo del connettore — endpoint, metodi, payload di esempio. Rudimentale ma funzionale.

Senza una specifica, Zero funziona comunque — deve solo indovinare di più sulla forma dei parametri. Per i connettori personalizzati usati di frequente, una specifica si ripaga rapidamente.

Condivisione tra workspace

I connettori personalizzati sono per impostazione predefinita con ambito workspace. Due team nella stessa org possono ciascuno mantenere il proprio connettore personalizzato per la stessa API interna. Per le organizzazioni che vogliono una configurazione canonica unica:

  • Connettori a livello di org enterprise. Disponibili nei piani enterprise. Configurati una volta a livello di org; compaiono in ogni workspace sotto quella org. Consigliati per le API interne che usano tutti.
  • Pacchetto di connettore. Per org molto grandi, il team interno della piattaforma può pubblicare un connettore personalizzato come pacchetto con versione; i workspace lo installano e ricevono gli aggiornamenti automaticamente.

Sicurezza e limiti di frequenza

  • Credenziali. Crittografate a riposo con chiavi per singolo workspace. Mai visibili dopo il salvataggio; solo re-inseribili.
  • Audit per chiamata. Ogni richiesta attraverso un connettore personalizzato compare nel registro della sessione con metodo, URL, codice di stato e tempistica.
  • Limiti di frequenza. Applicati dal servizio a monte. Zero gestisce le risposte 429 con backoff esponenziale fino a un limite configurato per workspace.
  • Percorsi in allow-list. Opzionale: limita Zero a pattern URL specifici. Riduce il raggio d'azione se una chiave del connettore è troppo privilegiata.
  • Sola lettura per impostazione predefinita. Un nuovo connettore personalizzato è contrassegnato come sola lettura. Concedere l'accesso in scrittura richiede una configurazione esplicita per workspace.

Insidie comuni

  • Chiavi API troppo ampie. Se il tuo servizio lo supporta, genera una chiave con ambito ridotto per Zero anziché riutilizzare la tua chiave admin personale. Più facile da ruotare e verificare.
  • Schemi mancanti. Senza una specifica OpenAPI o una descrizione inline, Zero indovina la forma dei parametri. Funziona per i casi semplici e si rompe con gli oggetti annidati. Fornisci una specifica quando puoi.
  • URL di base non testati. Fai sempre clic su Test connection dopo la configurazione. Un 401 o 404 in questa fase è molto meglio di un 401 in una sessione critica.
  • Dimenticare di ruotare. Imposta un promemoria in calendario per ruotare le chiavi ogni trimestre. La rotazione della chiave del connettore è un clic in VM0; è la rotazione a monte a richiedere la maggior parte del tempo.

Cosa viene dopo

  • Consulta Skills per catturare i flussi di lavoro ripetuti con connettori personalizzati.
  • Consulta Permissions per capire come vengono gestite le credenziali dei connettori personalizzati.
  • Consulta il Catalog prima di costruire un connettore personalizzato — il tuo servizio potrebbe essere già supportato.