Autenticazione e ambiti
Autentica le richieste all’API di AI Glot con le chiavi dello spazio di lavoro o i token OAuth, scegli gli ambiti minimi e rinnova le credenziali senza esporre i segreti.
Invia una chiave API dello spazio di lavoro o un token di accesso OAuth come credenziale bearer:
Authorization: Bearer aig_live_••••••••Non inserire mai una credenziale nella stringa di query. Gli URL vengono copiati nei log, nella cronologia del browser e negli header referrer.
Chiavi API dello spazio di lavoro
Un amministratore crea le chiavi da Strumenti per sviluppatori, nella scheda API. Il segreto completo viene mostrato una sola volta; AI Glot conserva solo un hash protetto. In uno spazio di lavoro possono essere attive fino a 10 chiavi.

- Nome. Indica l’integrazione che userà la chiave, ad esempio un processo CI o un servizio. Usa una chiave distinta e con nome per ogni integrazione.
- Autorizzazioni. Scegli un preset: Sola lettura, Gestione glossari o Accesso completo. In alternativa, apri Avanzate per selezionare i singoli ambiti. Parti dal set minimo necessario all’integrazione.
- Scadenza. Scegli Nessuna scadenza oppure una scadenza tra 30, 90 o 365 giorni.
- Crea chiave. Il segreto completo viene mostrato subito dopo la creazione, una sola volta. Copialo subito: non sarà possibile visualizzarlo di nuovo.
Rinnovo di una chiave
Nell’elenco delle chiavi è disponibile l’azione Rinnova. Genera una sostitutiva con lo stesso nome, gli stessi ambiti e la stessa scadenza, quindi revoca quella originale nella stessa operazione. La vecchia chiave smette di funzionare immediatamente, viene contrassegnata come replaced anziché semplicemente revocata e viene registrata la chiave che l’ha sostituita.
È una scelta intenzionale: si rinnova una chiave perché il segreto potrebbe essere stato compromesso, e una chiave che continua a funzionare per un’altra ora continua a funzionare anche per chi l’ha sottratta. Per un passaggio pianificato senza interruzioni, crea invece una seconda chiave, aggiorna l’integrazione per usarla, verifica che la vecchia non sia più utilizzata e poi revocala.
Token OAuth
La CLI e i client MCP compatibili possono usare OAuth 2.1. OAuth è consigliato per le persone, perché la connessione registra chi l’ha autorizzata e rispetta i limiti di accesso di quel membro. Le chiavi API restano la scelta giusta per CI e servizi backend.
Ambiti
Questi ambiti sono attualmente supportati:
| Ambito | Consente di |
|---|---|
account:read | Consultare l’identità dello spazio di lavoro, il piano, le funzionalità, i limiti e il riepilogo dei crediti |
usage:read | Consultare i totali di utilizzo e i relativi intervalli temporali |
batches:read | Elencare le traduzioni, verificarne l’avanzamento e scaricare i risultati completati |
batches:create | Creare una traduzione, pianificarla e approvarla. L’approvazione consuma i crediti dello spazio di lavoro |
batches:write | Rinominare e archiviare le traduzioni e annullare quelle 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 un ambito, viene restituito 403 insufficient_scope.
Ambito riservato
Oggi è possibile concedere un altro ambito, ma nessun endpoint lo supporta ancora. Compare nella schermata di consenso OAuth e nel preset Accesso completo del dashboard. Per questo lo documentiamo invece di nasconderlo: un’autorizzazione che ti viene chiesto di approvare deve essere sempre consultabile nel riferimento.
| Ambito | Consentirà di | Stato |
|---|---|---|
webhooks:write | Creare, modificare ed eliminare i webhook che avvisano i tuoi sistemi al termine delle attività | Non ancora disponibile |
È stato introdotto in anticipo affinché una credenziale concessa oggi continui a funzionare quando la funzionalità sarà disponibile, senza dover richiedere una seconda approvazione. Per determinare cosa può fare davvero una credenziale, leggi capabilities in GET /v1/account, non gli ambiti concessi. Un ambito può essere assegnato anche prima che esista l’endpoint corrispondente. Per caricare un file non serve un ambito dedicato: i file vengono inviati con la chiamata di creazione, usando batches:create.
Limiti di accesso dei membri
Gli amministratori dello spazio di lavoro possono limitare l’accesso agli strumenti per sviluppatori dei membri. Un client OAuth riceve l’intersezione tra gli ambiti richiesti e quelli a cui il membro che approva la connessione può accedere. Riconnettersi richiedendo autorizzazioni più ampie non permette di aggirare un limite di sola lettura.
Per impostazione predefinita, i nuovi spazi di lavoro includono tutti gli ambiti nei limiti di accesso dei membri, compreso batches:create. Un membro può già avviare una traduzione dall’app web, quindi i limiti corrispondono a ciò che può fare lì. Gli spazi di lavoro creati prima del 31 agosto 2026 mantengono i limiti esistenti, che escludevano batches:create. L’unico ambito che consuma crediti richiede una scelta consapevole: un agente che continua a effettuare richieste con una credenziale delegata potrebbe esaurire l’intera disponibilità mensile prima che qualcuno se ne accorga, e i crediti spesi non possono essere recuperati. Un amministratore può deselezionarlo, o deselezionare qualsiasi altro ambito, nella scheda Autorizzazioni di Strumenti per sviluppatori oppure per un singolo membro dalla pagina Team.