Authentication & Scopes
Personal access tokens
Create tokens in the KolWrite app under Settings → Account → API access. Tokens look like kol_..., are shown once at creation, and act as you: they see your files, spend your credits, and honor your plan limits. Send the token either way — both are equivalent:
Authorization: Bearer kol_...
X-API-Key: kol_...- Expiry: tokens don't expire by default; you can set 7/30/90 days or a custom date at creation.
- Revocation: revoke any token in the app; it takes effect immediately.
- Tokens can never manage tokens, delete your account, or reach administrative endpoints — regardless of scopes.
Scopes
A token can only call endpoints covered by its granted scopes. Every operation in the reference is annotated with its required scope (x-required-scope in the OpenAPI spec).
| Scope | Grants |
|---|---|
files:read | List and download files, folders, media, and uploads; read storage usage |
files:write | Upload files, register media, create or update folders and workspaces |
jobs:read | Read job status, queue position, results, and job artifacts |
jobs:write | Create and cancel jobs (transcription, caption burn); reorder the queue |
transcripts:read | Read transcripts, versions, and export download URLs |
transcripts:write | Save new transcript versions and restore previous ones |
ai:use | Use KolWrite managed AI (chat, embeddings, fast transcription); spends credits |
shares:read | List and inspect public share links |
shares:write | Create, update, rotate, and revoke public share links |
devices:read | List signed-in device sessions |
devices:write | Log out device sessions |
account:read | Read feature flags and app experience preferences |
account:write | Update app experience preferences |
billing:read | Read credit balance, ledger, and grants |
Presets in the app: Read only (all *:read), Automation (files:*, jobs:*, transcripts:read, billing:read), Full access.
Scope errors
Missing scope on a covered endpoint:
{"detail": {"code": "insufficient_scope",
"message": "This endpoint requires the 'jobs:write' scope",
"required_scope": "jobs:write"}}Endpoint outside the public token surface:
{"detail": {"code": "pat_route_not_allowed",
"message": "This endpoint is not available to personal access tokens"}}Both return HTTP 403. Invalid or revoked tokens return HTTP 401 with invalid_api_key.
Credits and billing
Jobs reserve credits when created and settle on completion; AI calls meter per token usage. Check spend with the billing:read scope via GET /api/v1/billing/balance and GET /api/v1/billing/ledger.