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

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:

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

Endpoint fuori dalla superficie pubblica dei token:

{"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

Versione Markdown di questa pagina