{"revision":"0ed62d2c742f8e20","language":"it","entry":{"id":"api-keys","kind":"guide","group":"guides","title":"Usa una chiave API per sviluppatori","summary":"Dai a un’integrazione da server una quota condivisa senza concedere autorità sulla scheda Veil.","sections":[{"kind":"paragraph","text":"Le letture pubbliche e la verifica dei messaggi funzionano anche senza una chiave API. Una chiave per sviluppatori dà al tuo server una quota separata, condivisa da tutte le chiavi della stessa persona o organizzazione. Apri /developers dal tuo account per gestirle."},{"kind":"heading","text":"Crea e conserva la chiave"},{"kind":"paragraph","text":"Un dispositivo attivo firma la creazione. Una persona gestisce le proprie chiavi; per un’organizzazione serve un proprietario con appartenenza accettata. Scegli un nome, il permesso read e/o verify e una scadenza da 1 a 365 giorni. Il valore predefinito è 90 giorni. Ogni titolare può avere 20 chiavi non scadute e non revocate, comprese quelle sospese."},{"kind":"paragraph","text":"La risposta di creazione mostra secret una sola volta. Veil ne conserva solo l’hash SHA-256. Metti il valore nella configurazione segreta del tuo server e mandalo nell’intestazione Authorization Bearer. Non inserirlo in URL, repository, JavaScript pubblico o screenshot condivisi. La chiave privata di firma del dispositivo Veil resta nel dispositivo."},{"kind":"code","language":"shell","code":"curl -fsS \\\n  -H \"Authorization: Bearer $VEIL_API_KEY\" \\\n  \"https://veil.rip/v1/lookup?key=73ad6159583a43f8ad230a215b758db680efcd3ce32ab8e83c622eeca883e68a\""},{"kind":"heading","text":"Come funziona la quota"},{"kind":"paragraph","text":"Il contenitore del titolare contiene per impostazione predefinita 600 richieste e si ricarica a 600 al minuto. La verifica dei messaggi usa quel contenitore e uno aggiuntivo da 120 verifiche, ricaricato a 120 al minuto. Sono token bucket continui, quindi una breve raffica può consumare il saldo disponibile. I contatori sono in PostgreSQL e sopravvivono ai riavvii. Creare o ruotare una chiave non li azzera."},{"kind":"paragraph","text":"Le letture autenticate usano la quota del titolare al posto delle 300 letture anonime al minuto per IP. Restano un limite esterno di 3000 richieste con chiave al minuto per IP e una concorrenza limitata per l’autenticazione. Le chiamate senza chiave mantengono i limiti attuali. Le chiavi API non aumentano i limiti di scritture firmate, creazione di schede, accoppiamento o collegamento degli account."},{"kind":"paragraph","text":"Lo staff può applicare un limite aggiuntivo per chiave, una quota personalizzata del titolare o un limite giornaliero. La quota di una chiave non si somma al totale del titolare. I limiti giornalieri ripartono a mezzanotte UTC. Le richieste API ammesse contano anche quando l’endpoint risponde poi con un errore. Quelle fermate da una quota API vengono contate separatamente."},{"kind":"heading","text":"Leggi le intestazioni di risposta"},{"kind":"paragraph","text":"X-RateLimit-Limit e X-RateLimit-Remaining descrivono il contenitore effettivo della richiesta. X-RateLimit-Reset usa secondi Unix per indicare quando il contenitore può essere di nuovo pieno senza altre richieste. X-RateLimit-Resource indica requests, verification, key o daily. Una risposta 429 rate_limited include Retry-After in secondi, calcolato per la prossima richiesta ammissibile."},{"kind":"paragraph","text":"GET /v1/rate-limit restituisce le quote attuali di chiave e titolare senza consumare la quota principale. Richiede comunque una chiave valida e conta nel limite esterno per IP. Le letture firmate di gestione mostrano l’uso giornaliero e gli ultimi 31 giorni di storia. Le risposte con chiave API usano no-store."},{"kind":"heading","text":"Rotazione, revoca e sospensione"},{"kind":"paragraph","text":"Crea una chiave sostitutiva, aggiorna l’integrazione e revoca la vecchia. La revoca è definitiva. Lo staff può sospendere e riattivare singole chiavi, revocarle definitivamente o sospendere tutto l’accesso API di un titolare. Creare un’altra chiave non aggira la sospensione del titolare. Restano valide la scadenza delle chiavi e la sospensione o cancellazione della scheda."},{"kind":"paragraph","text":"Le chiavi non valide, scadute o revocate danno 401 invalid_api_key. I permessi insufficienti danno 403 api_key_scope. Una chiave sospesa dà 403 api_key_suspended; l’accesso bloccato del titolare dà 403 developer_suspended. Queste richieste non passano mai automaticamente all’accesso anonimo."},{"kind":"heading","text":"Accesso pubblico dal browser"},{"kind":"paragraph","text":"Le chiavi Bearer segrete sono per client server o locali. Authorization non è aperta dal CORS pubblico. Le integrazioni nel browser possono continuare a chiamare gli endpoint pubblici in forma anonima. La gestione delle chiavi usa la firma del dispositivo, non la chiave Bearer. Le chiavi API non conferiscono ruoli di staff o autorità per pubblicare versioni di identità."},{"kind":"heading","text":"Controlla l’attività privata"},{"kind":"paragraph","text":"Creazione, revoca del titolare, azioni dello staff e limiti personalizzati conservano una ricevuta privata con l’esatta richiesta firmata di gestione. Titolari e staff autorizzato possono leggerla. I segreti non compaiono nelle ricevute o nel registro pubblico delle identità. I dati d’uso contengono contatori aggregati, senza messaggi, query di ricerca o indirizzi IP."},{"kind":"links","ids":["developer-account","create-api-key","developer-keys","revoke-api-key","api-key-audit","rate-limit"]},{"kind":"paragraph","text":"Le chiavi di firma dei dispositivi e le chiavi API delle integrazioni hanno durate separate. Revocare un dispositivo non revoca le chiavi API che ha emesso. Dopo la compromissione di un dispositivo controlla le ricevute private e revoca anche le chiavi API coinvolte."}],"related":["browser-apps","limits","signed-requests","errors"],"errors":[],"documentationUrl":"https://veil.rip/docs/api-keys?lang=it"}}