API Keys

Le API keys permettono a script e applicazioni esterne di accedere a XIQUIL usando l’API REST, senza passare dal flusso di login web. Ogni utente può avere una propria chiave; l’admin vede tutte le chiavi generate.

A cosa serve

Integrare XIQUIL con script personali (importazione dati, report automatici, sincronizzazioni)
Collegare dashboard esterne (Grafana, n8n, Home Assistant) ai dati finanziari
Sviluppare plugin custom che accedono all’API
Avere un canale di autenticazione separato dal browser, che bypassa CSRF e MFA

Come si usa

Dal menu utente, apri API Keys
Clicca Genera nuova chiave
La chiave è mostrata una sola volta — salvala in un gestore di password o file sicuro
Inviala in uno dei due header HTTP supportati:
- X-API-Key: <chiave> (raccomandato — coerente con la UI e con la maggioranza degli HTTP client)
- Authorization: Bearer <chiave> (compatibile con tooling OAuth-style come curl --oauth2-bearer)
Per revocarla, clicca Rigenera o Elimina

Lista API Keys con colonna chiave display, data creazione e pulsanti Rigenera/Elimina La lista delle API Keys con la chiave display sempre visibile e il pulsante per rigenerarla o eliminarla.

Concetti chiave

Prefisso riconoscibile: tutte le chiavi iniziano con un prefisso comune per distinguerle a colpo d’occhio nei log o nei file di config
Una per utente: ogni utente ha al massimo una chiave attiva. Rigenerarla invalida la precedente
Stessi permessi dell’utente: la chiave eredita i permessi dell’utente — non è un accesso admin implicito
Tracking device: l’uso della chiave viene tracciato per IP e user-agent (vedi tab “Utilizzo”). last_used_at viene aggiornato a ogni richiesta, anche su endpoint di sola lettura
No CSRF, no MFA: è un secondo fattore di per sé (segreto noto solo al titolare), quindi salta MFA e CSRF
Revoca immediata: cancellare la chiave la invalida all’istante