Autenticazione e scope
Autentica le richieste all'API di AI Glot con chiavi di workspace o token OAuth, seleziona gli scope minimi e ruota le credenziali senza esporre i secret.
Invia una chiave API del workspace o un token di accesso OAuth come credenziale Bearer:
Authorization: Bearer aig_live_••••••••Non inserire mai una credenziale all’interno di una query string. Gli URL vengono salvati nei log, nella cronologia del browser e nelle intestazioni Referer.
Chiavi API del workspace
Un amministratore può creare le chiavi in Developer tools. Il secret completo viene mostrato una sola volta; AI Glot memorizza unicamente un hash protetto. In un workspace possono essere attive fino a 10 chiavi.
Utilizza una chiave distinta con un nome dedicato per ciascuna integrazione.
Ruotare una chiave
L’elenco delle chiavi offre l’azione Rotate. Questa opzione genera una chiave sostitutiva con lo stesso nome, gli stessi scope e la medesima scadenza, revocando contemporaneamente l’originale nella stessa operazione. La vecchia chiave smette di funzionare immediatamente, viene contrassegnata come replaced anziché semplicemente revocata e registra quale chiave le è succeduta.
Si tratta di un comportamento intenzionale: la rotazione viene eseguita perché un secret potrebbe essere compromesso, e una chiave che continua a funzionare per un’altra ora rimarrebbe attiva anche per chi l’ha sottratta. Per un passaggio pianificato senza tempi di inattività (zero-downtime), crea invece una seconda chiave, migra l’integrazione su quest’ultima, verifica che la vecchia chiave non sia più utilizzata e infine revocala.
Token OAuth
La CLI e i client MCP compatibili possono utilizzare OAuth 2.1. OAuth è consigliato per le persone fisiche perché la connessione registra chi l’ha approvata e rispetta il limite massimo di accesso di tale membro. Le chiavi API restano invece la scelta ideale per la CI e i servizi di backend.
Scope
Gli scope attualmente supportati sono:
| Scope | Consente di |
|---|---|
account:read | Visualizzare identità del workspace, piano, funzionalità abilitate, limiti e riepilogo dei crediti |
usage:read | Visualizzare totali di utilizzo e intervalli temporali |
batches:read | Elencare le traduzioni, monitorare l’avanzamento e scaricare i risultati completati |
batches:create | Creare una traduzione, pianificarla e approvarla. L’approvazione consuma crediti del workspace |
batches:write | Rinominare e archiviare traduzioni, nonché annullare una traduzione in corso. L’annullamento addebita il lavoro già completato |
glossaries:read | Elencare e recuperare i glossari |
glossaries:write | Creare, aggiornare, sostituire o eliminare i glossari |
Se manca uno scope richiesto, viene restituito l’errore 403 insufficient_scope.
Scope riservati
Attualmente è possibile concedere altri due scope, sebbene nessun endpoint li supporti ancora. Compaiono nella schermata di consenso OAuth e nel preset Full access della dashboard, motivo per cui sono documentati qui anziché nascosti: un’autorizzazione richiesta dovrebbe essere sempre consultabile nella documentazione di riferimento.
| Scope | Consentirà di | Stato |
|---|---|---|
files:write | Caricare file nel workspace come passaggio separato, anziché inviarli con la chiamata di creazione | Non ancora disponibile |
webhooks:write | Creare, modificare ed eliminare i webhook che notificano i tuoi sistemi al termine del lavoro | Non ancora disponibile |
Questi scope sono stati introdotti in anticipo affinché una credenziale concessa oggi continui a funzionare nel momento in cui la funzionalità verrà rilasciata, senza richiedere una seconda approvazione. Per determinare cosa può effettivamente fare una credenziale, controlla capabilities su GET /v1/account anziché gli scope concessi. Uno scope può infatti essere posseduto prima ancora che l’endpoint sottostante sia disponibile.
Limite massimo per i membri
Gli amministratori del workspace possono limitare l’accesso da sviluppatore per i membri. Un client OAuth riceve l’intersezione tra ciò che ha richiesto e ciò che il membro approvante è autorizzato a utilizzare. Riconnettersi con una richiesta più ampia non consente di aggirare un limite di sola lettura.
batches:create è escluso dal limite predefinito per i membri. Tutti gli altri scope vengono concessi automaticamente alla connessione di un membro; lo scope che consuma crediti, invece, non lo è. Altrimenti, un agent che opera in ciclo con una credenziale delegata potrebbe consumare l’intera quota mensile prima che qualcuno se ne accorga, e i crediti spesi non possono essere ripristinati. Un amministratore del workspace può estendere deliberatamente questo limite qualora sia richiesta la traduzione avviata da agent.