# Autenticazione e ambiti

## Token di accesso personale

Crea i token nell’app KolWrite (**Impostazioni → Account → Accesso API**).
I token hanno la forma `kol_...`, vengono mostrati una sola volta alla creazione e agiscono come **te**:
vedono i tuoi file, spendono i tuoi crediti e rispettano i limiti del tuo piano.

Invia il token in uno dei due modi; sono equivalenti:

```
Authorization: Bearer kol_...
X-API-Key: kol_...
```

- **Scadenza**: per impostazione predefinita i token non scadono; alla creazione puoi impostare 7/30/90 giorni o una
  data a scelta.
- **Revoca**: revoca qualsiasi token nell’app (oppure con `DELETE
  /api/v1/api-keys/{id}` da una sessione autenticata). Ha effetto immediato.
- I token non possono mai gestire token, eliminare il tuo account né raggiungere endpoint
  amministrativi, qualunque sia l’ambito.

## Ambiti

Un token può chiamare solo gli endpoint coperti dagli ambiti concessi. Ogni
operazione del [riferimento](/) indica l’ambito richiesto
(`x-required-scope` nella [specifica OpenAPI](/openapi.json)).

| Ambito | Consente |
|---|---|
| `files:read` | Elencare e scaricare file, cartelle, media e caricamenti; leggere l’uso dello spazio |
| `files:write` | Caricare file, registrare media, creare/aggiornare cartelle e spazi di lavoro |
| `jobs:read` | Leggere stato dei job, posizione in coda, risultati e artefatti dei job |
| `jobs:write` | Creare e annullare job (trascrizione, incorporamento dei sottotitoli); riordinare la coda |
| `transcripts:read` | Leggere trascrizioni, versioni e URL di download delle esportazioni |
| `transcripts:write` | Salvare nuove versioni di trascrizione e ripristinare quelle precedenti |
| `ai:use` | Usare l’IA gestita di KolWrite (chat, embeddings, trascrizione rapida); consuma crediti |
| `copilot:write` | Eseguire IA a consumo e salvare i turni nel Copilot generale o nel Copilot di una trascrizione autorizzata |
| `shares:read` | Elencare e consultare i link di condivisione pubblici |
| `shares:write` | Creare, aggiornare, ruotare e revocare i link di condivisione pubblici |
| `devices:read` | Elencare le sessioni dei dispositivi connessi |
| `devices:write` | Disconnettere le sessioni dei dispositivi |
| `account:read` | Leggere i flag delle funzioni e le preferenze di esperienza dell’app |
| `account:write` | Aggiornare le preferenze di esperienza dell’app |
| `billing:read` | Leggere saldo crediti, registro movimenti e concessioni |

Preimpostazioni nell’app: **Sola lettura** (tutti i `*:read`), **Automazione**
(`files:*`, `jobs:*`, `transcripts:read`, `billing:read`), **Accesso completo**.

## Errori di ambito

Ambito mancante su un endpoint coperto:

```json
{"detail": {"code": "insufficient_scope",
            "message": "This endpoint requires the 'jobs:write' scope",
            "required_scope": "jobs:write"}}
```

Endpoint fuori dalla superficie pubblica dei token:

```json
{"detail": {"code": "pat_route_not_allowed",
            "message": "This endpoint is not available to personal access tokens"}}
```

Entrambi restituiscono HTTP 403. I token non validi o revocati restituiscono HTTP 401 con
`invalid_api_key`.

## Crediti e fatturazione

I job riservano crediti alla creazione e li regolano al completamento; le chiamate IA vengono misurate
a consumo di token. Controlla la spesa con `billing:read`:

- `GET /api/v1/billing/balance`
- `GET /api/v1/billing/ledger`