Creare una chiave API

Genera, gestisci e revoca chiavi API per l'API di Vulgate.

21 mag 2026

Le chiavi API permettono al tuo codice di autenticarsi su Vulgate proprio come fa l'app web. Ogni chiave è associata a un singolo team / Organizzazione e ne eredita i permessi.

Generare una nuova chiave

  1. Apri l'app Vulgate.
  2. Dalla barra laterale, scegli Impostazioni → API.
  3. Clicca Crea una nuova chiave API.
  4. Dai alla chiave un nome che spieghi a cosa serve ("Produzione", "CI/CD", "Dev locale"). I nomi ti aiutano a identificare e revocare la chiave giusta in seguito.
  5. Clicca Crea.

Vulgate mostra il valore della chiave una sola volta — copialo immediatamente. Non lo mostriamo mai più; l'unico recupero è generarne una nuova.

Conservare la chiave

Non committare mai una chiave nel controllo versione. I due pattern sicuri sono:

  • Variabile d'ambiente nella tua shell o CI:
export VULGATE_API_KEY=...
  • File .env caricato a runtime (e .env elencato nel tuo .gitignore):
VULGATE_API_KEY=...

Poi leggila dal tuo codice:

import os
api_key = os.environ["VULGATE_API_KEY"]

const apiKey = process.env.VULGATE_API_KEY!;

Usare la chiave

Ogni richiesta ha bisogno della chiave nell'header Authorization:

curl https://vulgate.ai/api/search \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

Elencare le chiavi esistenti

La pagina Impostazioni → API mostra ogni chiave creata per il team corrente, con il nome della chiave e la data di creazione.

Eliminare una chiave

  1. Apri Impostazioni → API.
  2. Trova la chiave nell'elenco.
  3. Clicca Elimina chiave API.
  4. Conferma.

L'eliminazione ha effetto entro pochi secondi. Qualsiasi richiesta che usa una chiave eliminata riceve HTTP 401.

Best practice per le chiavi

  • Una chiave per app. Mescolare chiavi tra app significa che non puoi revocarne una senza rompere l'altra.
  • Usa nomi chiari. Non costano nulla e ti salvano in un incidente.
  • Ruota periodicamente. Genera una nuova chiave, deployala, poi elimina la vecchia.
  • Tieni le chiavi fuori dai log. Configura la tua libreria di logging per oscurare gli header Authorization.

Quale ambito ha una chiave?

Ogni chiave API è associata a un singolo team e porta i permessi del proprietario del team. Questo significa che una chiave API può fare tutto ciò che può fare il Proprietario del team — incluso caricare, cercare e leggere documenti in quel team.

Correlati

Cerca nell'assistenza