AI Glot websiteOpen AI Glot
REST APIAutenticazione e ambiti

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 header
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.

Finestra di creazione di una chiave API con nome, preset di autorizzazioni, scadenza e pulsante Crea chiave

Crea una chiave con nome e scegli le autorizzazioni
  1. 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.
  2. 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.
  3. Scadenza. Scegli Nessuna scadenza oppure una scadenza tra 30, 90 o 365 giorni.
  4. 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:

AmbitoConsente di
account:readConsultare l’identità dello spazio di lavoro, il piano, le funzionalità, i limiti e il riepilogo dei crediti
usage:readConsultare i totali di utilizzo e i relativi intervalli temporali
batches:readElencare le traduzioni, verificarne l’avanzamento e scaricare i risultati completati
batches:createCreare una traduzione, pianificarla e approvarla. L’approvazione consuma i crediti dello spazio di lavoro
batches:writeRinominare e archiviare le traduzioni e annullare quelle in corso. L’annullamento addebita il lavoro già completato
glossaries:readElencare e recuperare i glossari
glossaries:writeCreare, 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.

AmbitoConsentirà diStato
webhooks:writeCreare, 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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.