Autenticazione e ambiti
Token di accesso personale
L’accesso API è self-service: quando il tuo account ha acquistato crediti, attivalo in Impostazioni → Account → Accesso API. Le chiamate usano i tuoi crediti.
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/balanceGET /api/v1/billing/ledger
Limiti e spesa
- I crediti sono il limite finale: le chiamate a pagamento (lavori di trascrizione e il proxy AI) usano crediti e, senza saldo, restituiscono HTTP 402
insufficient_credits. - Il tuo livello d’uso sale da solo con i crediti acquistati e l’età dell’account (Start, Build, Scale, Established). Ogni livello fissa un tetto mensile, richieste al minuto e richieste parallele per chiave.
- Nell’app puoi fissare un budget mensile per l’account e, per chiave, un tetto mensile, indirizzi IP consentiti e una scadenza. Oltre il budget o il tetto, le chiamate a pagamento restituiscono HTTP 402
api_monthly_budget_reachedoapi_key_cap_reached; troppe richieste restituiscono HTTP 429 conRetry-After. - Una spesa insolita invia prima un’email; solo picchi estremi mettono in pausa una chiave, e puoi riprenderla nell’app. Ruotando una chiave, la vecchia può restare valida fino a 7 giorni.