Usa una chiave API per sviluppatori
Dai a un’integrazione da server una quota condivisa senza concedere autorità sulla scheda Veil.
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.
Crea e conserva la chiave#
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.
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.
curl -fsS \
-H "Authorization: Bearer $VEIL_API_KEY" \
"https://veil.rip/v1/lookup?key=73ad6159583a43f8ad230a215b758db680efcd3ce32ab8e83c622eeca883e68a"Come funziona la quota#
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.
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.
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.
Leggi le intestazioni di risposta#
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.
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.
Rotazione, revoca e sospensione#
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.
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.
Accesso pubblico dal browser#
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à.
Controlla l’attività privata#
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.
- GETLeggi un account API titolareLeggi limiti condivisi, saldi delle quote, uso, chiavi e attività privata.
/v1/developer/accounts/{n} - POSTCrea una chiave di integrazioneUna persona o un proprietario dell’organizzazione firma la richiesta per emettere una chiave Bearer segreta.
/v1/developer/accounts/{n}/keys - GETElenca le chiavi delle integrazioniElenca i metadati delle chiavi senza rivelare i segreti.
/v1/developer/accounts/{n}/keys - DELETERevoca una chiave di integrazioneDisattiva definitivamente una chiave di questa scheda.
/v1/developer/accounts/{n}/keys/{id} - GETLeggi l’attività privata delle chiavi APIControlla le ricevute di gestione e le firme originali dei dispositivi.
/v1/developer/accounts/{n}/audit - GETControlla la quota di una chiave APILeggi le quote attuali di titolare e chiave senza consumare la quota principale.
/v1/rate-limit
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.