Documentazione

Documentazione

API di gestione

Una chiave di gestione permette ai tuoi sistemi di creare, raggruppare, limitare e revocare le chiavi API del tuo account e di leggere quanto hanno speso, tramite l’API. Non può chiamare un modello.

A cosa serve

Alcune integrazioni danno a ciascuno dei loro clienti, team o utenti una chiave API propria, raccolgono le chiavi di ogni cliente in un gruppo, fissano un tetto a quanto può spendere un gruppo e rileggono il costo per chiave o per gruppo. Nella pagina Chiavi API va bene per poche chiavi. Per di più, una chiave di gestione permette a uno script o al tuo strumento di amministrazione di fare lo stesso tramite l’API.

Una chiave di gestione è una credenziale diversa da una chiave API. Non è accettata dove è accettata una chiave API: non può chiamare /v1/chat/completions, /v1/messages né alcun altro percorso di modello. Funziona solo su /v1/management/, e lì una chiave API non funziona.

Crea una chiave di gestione

  • Apri la pagina Chiavi API e scorri in fondo. Sotto «Chiavi di gestione», scegli «Nuova chiave di gestione». Il riquadro resta chiuso finché non lo apri.
  • Dai un nome alla chiave, per esempio sincronizzazione fatturazione, così la pagina può indicare quale programma ha fatto ogni modifica.
  • Inserisci gli indirizzi da cui può essere chiamata, uno per riga: un singolo indirizzo come 203.0.113.7 o un intervallo come 203.0.113.0/24. Senza un elenco di indirizzi consentiti, chiunque abbia la chiave può usarla, e la finestra ti avvisa se lasci l’elenco vuoto.
  • Copia la chiave quando viene mostrata. Viene mostrata una sola volta: Kunavo ne conserva solo un hash.

Un account può avere due chiavi di gestione attive contemporaneamente. Revocane una per fare spazio a un’altra.

Chiamala

Invia la chiave come token Bearer a https://api.kunavo.com/v1/management. Le chiavi di gestione non sono accettate da un browser: le loro risposte non hanno intestazioni CORS, quindi una pagina di un altro sito non può chiamarle. Una chiave va tenuta sul tuo server, mai nel codice front-end.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Le risposte sono JSON. Gli errori hanno la stessa forma del resto dell’API: un oggetto error con un message, un type, un code e, dove serve, il param sbagliato. Questi sono gli stati che incontrerai:

StatoCosa significa
401La chiave manca, è scritta male o è revocata, oppure il suo account è sospeso o in revisione.
403La chiave ha un elenco IP consentiti e la richiesta è arrivata da un indirizzo che non è nell’elenco.
404Il gruppo o la chiave non esiste, è eliminato o appartiene a un altro account. I tre casi rispondono allo stesso modo, quindi un id di un altro account non rivela nulla.
409La modifica è in conflitto con lo stato dell’account: un nome di gruppo già in uso, una chiave revocata, o l’account al tetto di 500 chiavi attive.
429Questa chiave ha fatto 60 richieste nell’ultimo minuto. L’intestazione Retry-After indica quanti secondi attendere.

Gruppi

GET /v1/management/groups elenca i gruppi dell’account, con il limite mensile di ciascuno e quante chiavi attive contiene. POST ne crea uno, con un monthly_limit_usd facoltativo; un nome già in uso dà un 409. PATCH /v1/management/groups/{id} cambia il nome o il limite: invia null per nessun limite e 0 per sospendere tutte le chiavi del gruppo senza revocarne nessuna. DELETE elimina un gruppo, e le sue chiamate conservano il suo nome nella pagina Utilizzo. Le sue chiavi restano attive e non hanno più un gruppo, a meno che tu non aggiunga ?revoke_keys=true, che le revoca tutte.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001", "monthly_limit_usd": 50}'

Chiavi

GET /v1/management/keys elenca le chiavi, dalla più recente. Una pagina contiene 50 chiavi, e limit porta il valore a 100. status è per impostazione predefinita active, oppure revoked o all, e group_id restringe l’elenco a un gruppo. Quando has_more è true, passa next_after come after per leggere la pagina successiva. Il testo in chiaro di una chiave non viene mai elencato.

POST /v1/management/keys crea una chiave con un nome e, facoltativamente, un group_id, un monthly_limit_usd e un ip_allowlist. La risposta contiene il testo in chiaro nel campo key, una sola volta. Un POST ripetuto crea una seconda chiave, quindi prima di ritentarlo elenca le chiavi e cerca il suo nome.

curl https://api.kunavo.com/v1/management/keys \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'

PATCH /v1/management/keys/{id} cambia il nome, il gruppo, il limite o l’elenco consentiti di una chiave; un group_id pari a null la toglie dal suo gruppo. DELETE la revoca. Revocare una chiave già revocata non è un errore. Una chiave revocata non può essere modificata.

curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Utilizzo

GET /v1/management/usage riporta l’utilizzo dell’intero account fino a 90 giorni UTC, come GET /v1/usage riporta quello di una chiave. group_by accetta qualsiasi combinazione di group, api_key, model e day, e per impostazione predefinita è api_key. I dati hanno lo stesso significato che nella pagina Utilizzo: una chiamata conta nel gruppo in cui si trovava la sua chiave quando è stata fatta, una chiamata fallita non costa nulla, e il totale di un periodo coincide al centesimo con l’esportazione CSV degli stessi giorni. group_id e api_key_id restringono il report a un gruppo o a una chiave.

curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"
Le date sono giorni di calendario UTC, con entrambi gli estremi inclusi. Un end_date successivo a oggi viene letto come oggi, e la risposta riporta la data finale usata.

Tienila al sicuro

  • Imposta un elenco di indirizzi consentiti. Una chiave che funziona solo dagli indirizzi del tuo server vale poco per chi la ruba.
  • Tieni la chiave in un archivio di segreti sul server che esegue il tuo strumento. Non metterla mai in un browser, in un’app mobile o in un repository.
  • Se trapela, revocala in fondo alla pagina Chiavi API, oppure con DELETE su di essa. La finestra di revoca può revocare anche le chiavi create da quella chiave.
  • Ogni modifica che la chiave fa tramite l’API compare sotto «Chiavi di gestione» nella pagina Chiavi API, con l’ora, l’indirizzo di provenienza e la chiave che l’ha fatta: le ultime 50 modifiche. Le modifiche fatte a mano in quella pagina non sono elencate.
  • Una chiave smette di funzionare da sola quando il suo account viene sospeso o messo in revisione, e quando viene revocata.

Una chiave di gestione può fare 60 richieste al minuto. Fai una richiesta per ogni modifica e leggi un elenco a pagine, anziché una chiave alla volta.

I gruppi, i loro limiti mensili e il modo in cui vengono contati i dati sono spiegati nella pagina dei gruppi di chiavi. I dati di utilizzo sono gli stessi della pagina Utilizzo.