Autenticazione e scope
Autentica le richieste dell'API di AI Glot tramite chiavi di workspace o token OAuth, scegli gli scope minimi e ruota le credenziali senza esporre i segreti.
Invia una chiave API di workspace o un token di accesso OAuth come credenziale bearer:
Authorization: Bearer aig_live_••••••••Non inserire mai una credenziale in una query string. Gli URL vengono copiati nei log, nella cronologia del browser e negli header referrer.
Chiavi API di workspace
L’amministratore crea le chiavi negli Strumenti per sviluppatori. Il segreto completo viene mostrato una sola volta; AI Glot ne conserva solo un hash protetto. In un workspace possono essere attive fino a 10 chiavi.
Utilizza una chiave nominata separata per ogni integrazione.
Ruotare una chiave
L’elenco delle chiavi offre l’azione Ruota. Questa emette un sostituto con lo stesso nome, scope e scadenza, revocando l’originale nella stessa operazione. La vecchia chiave smette di funzionare immediatamente, viene contrassegnata come replaced (sostituita) anziché semplicemente revocata e registra quale chiave l’ha sostituita.
Questa scelta è deliberata: si ruota una chiave perché un segreto potrebbe essere stato compromesso, e una chiave che continua a funzionare per un’altra ora continuerà a funzionare per chiunque l’abbia sottratta. Per un passaggio pianificato senza interruzioni (zero-downtime), crea invece una seconda chiave, sposta l’integrazione su di essa, conferma che la vecchia chiave non sia più in uso e poi revocala.
Token OAuth
La CLI e i client MCP compatibili possono utilizzare OAuth 2.1. OAuth è consigliato per le persone, poiché la connessione registra chi l’ha approvata e rispetta il limite di accesso di quel membro. Le chiavi API rimangono la scelta più adatta per CI e servizi di backend.
Scope
Gli scope attualmente disponibili sono:
| Scope | Consente |
|---|---|
account:read | Identità del workspace, piano, funzionalità, limiti e riepilogo crediti |
usage:read | Totali di utilizzo e bucket temporali |
batches:read | Elencare le traduzioni, ispezionare l’avanzamento e scaricare i risultati completati |
batches:write | Rinominare e archiviare le traduzioni. Lo stesso scope copre anche l’arresto di una traduzione in corso, funzione non ancora disponibile |
glossaries:read | Elencare e recuperare i glossari |
glossaries:write | Creare, aggiornare, sostituire o eliminare i glossari |
La mancanza di uno scope restituisce 403 insufficient_scope.
Scope riservati
Al momento possono essere concessi altri tre scope, ma nessun endpoint li supporta ancora. Appaiono nella schermata di consenso OAuth e nel preset Full access della dashboard, quindi sono documentati qui anziché essere nascosti: un permesso che ti viene chiesto di approvare deve essere sempre rintracciabile nella documentazione di riferimento.
| Scope | Consentirà | Stato |
|---|---|---|
batches:create | Avviare una nuova traduzione e approvarne una dopo la fase di revisione. Entrambe le operazioni consumano crediti del workspace | Non ancora disponibile |
files:write | Caricare file nel workspace per poterli tradurre | Non ancora disponibile |
webhooks:write | Creare, modificare ed eliminare i webhook che notificano i tuoi sistemi al completamento del lavoro | Non ancora disponibile |
Esistono in anticipo affinché una credenziale concessa ora continui a funzionare il giorno in cui la funzionalità sarà rilasciata, senza un secondo round di approvazione. Fino ad allora, GET /v1/account riporterà capabilities.batch_creation: false e capabilities.webhooks: false, e le chiamate a tali endpoint saranno non disponibili indipendentemente dallo scope. Consulta i flag di capability invece degli scope concessi per decidere cosa può effettivamente fare una credenziale.
Limite membro (Member ceiling)
Gli amministratori del workspace possono limitare l’accesso degli sviluppatori per i membri. Un client OAuth riceve l’intersezione tra ciò che ha richiesto e ciò che il membro che approva può utilizzare. Riconnettersi con una richiesta più ampia non può bypassare un limite di sola lettura.