Autenticazione

Manda la chiave nell'header Authorization a ogni richiesta. Le chiavi hanno il prefisso vokse_sk_, così le riconosci al volo nei log (trattale come password e non metterle mai in un commit).

Authorization: Bearer vokse_sk_3f8a…

Apri Impostazioni → Chiavi API nell'app vokse e crea una chiave. Il segreto si vede una volta sola, al momento della creazione: copialo subito. Dai a ogni integrazione la sua chiave, così ne puoi revocare una senza rompere le altre.

1. Vai in Impostazioni → Chiavi API.
2. Premi «Crea chiave» e dalle il nome dell'integrazione.
3. Seleziona gli scope minimi che servono a quell'integrazione.
4. Copia il segreto: viene mostrato una sola volta.

Ogni chiave nasce dentro una famiglia e può agire solo su quella. Le rotte legate a una famiglia ne portano l'id nel percorso, ma raramente devi cercarlo: il segmento letterale current punta sempre alla famiglia a cui appartiene la chiave. Se ti serve l'id vero, recuperalo una volta:

curl -H "Authorization: Bearer vokse_sk_3f8a…" \     https://api.vokse.ai/households/current

Tutti gli esempi di questo riferimento usano current, quindi funzionano così come sono, con la sola chiave. Preferisci gli id espliciti? Copia il tuo da Impostazioni → Membri nell'app, oppure mandalo nell'header X-Household-Id invece che nel percorso.

Ogni chiave porta con sé un insieme di scope. Una richiesta passa solo se la chiave ha lo scope richiesto dall'endpoint (lo trovi nel badge su ogni endpoint). Gli scope sono di tre tipi:

• read:* dà accesso in sola lettura a una risorsa (sicuro, idempotente).
• write:* permette di creare, modificare ed eliminare su una risorsa.
• ai:* permette di usare le funzioni IA; vengono conteggiate sul tuo limite mensile.

Alla creazione puoi dare a una chiave una data di scadenza. Passata quella data, le richieste falliscono con API_KEY_EXPIRED. Per ruotare una chiave creane una nuova, mettila in produzione e poi revoca la vecchia: nessuna interruzione di servizio. Le chiavi revocate smettono di funzionare subito.