---
title: "Autenticazione e scope"
description: "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."
canonical: "https://ai-glot.com/docs/it/api/authentication"
updated: "2026-08-12"
---

# Autenticazione e scope

Invia una chiave API di workspace o un token di accesso OAuth come credenziale bearer:

```http title="Header di autorizzazione"
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](https://app.ai-glot.com/developer). 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.

![Dialogo di creazione chiave API](/docs/screenshots/platform/api-key-create.webp)

_Crea una chiave nominata e scegli i relativi scope_

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.

> **Warning**
>
> La rotazione non prevede periodi di grazia né finestre di sovrapposizione. Nel momento in cui ruoti la chiave, le richieste che utilizzano ancora il vecchio segreto falliranno con l'errore `api_key_revoked`. Sii pronto a implementare il nuovo segreto immediatamente.

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.

> **Danger**
>
> Tratta una chiave API di workspace come una password. Non caricarla in repository (commit), non incollarla in JavaScript lato client, non includerla in screenshot e non inviarla a un modello AI come testo di un prompt.