Authentifizierung und Berechtigungsbereiche

Persönliche Zugriffstoken

Erstellen Sie Tokens in der KolWrite-App (Einstellungen → Konto → API-Zugriff). Tokens sehen aus wie kol_..., werden bei der Erstellung nur einmal angezeigt und handeln als Sie: Sie sehen Ihre Dateien, verbrauchen Ihre Credits und unterliegen den Grenzen Ihres Tarifs.

Senden Sie das Token auf einem der beiden Wege – beide sind gleichwertig:

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

Ablauf: Tokens laufen standardmäßig nicht ab; bei der Erstellung können Sie 7/30/90 Tage oder ein eigenes Datum festlegen.
Widerruf: Widerrufen Sie jedes Token in der App (oder mit DELETE /api/v1/api-keys/{id} aus einer angemeldeten Sitzung). Das gilt sofort.
Tokens können nie Tokens verwalten, Ihr Konto löschen oder administrative Endpunkte erreichen – unabhängig von den Bereichen.

Berechtigungsbereiche

Ein Token kann nur Endpunkte aufrufen, die von den gewährten Bereichen abgedeckt sind. Jede Operation in der Referenz nennt ihren erforderlichen Bereich (x-required-scope in der OpenAPI-Spezifikation).

Bereich	Erlaubt
`files:read`	Dateien, Ordner, Medien und Uploads auflisten und herunterladen; Speichernutzung lesen
`files:write`	Dateien hochladen, Medien registrieren, Ordner und Arbeitsbereiche anlegen/ändern
`jobs:read`	Jobstatus, Warteschlangenposition, Ergebnisse und Job-Artefakte lesen
`jobs:write`	Jobs erstellen und abbrechen (Transkription, Untertitel einbrennen); Warteschlange umsortieren
`transcripts:read`	Transkripte, Versionen und Download-URLs für Exporte lesen
`transcripts:write`	Neue Transkriptversionen speichern und frühere wiederherstellen
`ai:use`	Die verwaltete KI von KolWrite nutzen (Chat, Embeddings, schnelle Transkription); verbraucht Credits
`copilot:write`	Abgerechnete KI-Dialoge ausführen und im allgemeinen Copilot oder im Copilot eines berechtigten Transkripts speichern
`shares:read`	Öffentliche Freigabelinks auflisten und ansehen
`shares:write`	Öffentliche Freigabelinks erstellen, ändern, rotieren und widerrufen
`devices:read`	Angemeldete Gerätesitzungen auflisten
`devices:write`	Gerätesitzungen abmelden
`account:read`	Feature-Flags und App-Einstellungen lesen
`account:write`	App-Einstellungen ändern
`billing:read`	Guthaben, Buchungsjournal und Gutschriften lesen

Voreinstellungen in der App: Nur lesen (alle *:read), Automatisierung (files:*, jobs:*, transcripts:read, billing:read), Vollzugriff.

Fehler bei Bereichen

Fehlender Bereich bei einem abgedeckten Endpunkt:

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

Endpunkt außerhalb der öffentlichen Token-Oberfläche:

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

Beide liefern HTTP 403. Ungültige oder widerrufene Tokens liefern HTTP 401 mit invalid_api_key.

Credits und Abrechnung

Jobs reservieren Credits bei der Erstellung und rechnen bei Abschluss ab; KI-Aufrufe werden nach Token-Verbrauch gemessen. Den Verbrauch prüfen Sie mit billing:read:

GET /api/v1/billing/balance
GET /api/v1/billing/ledger

Markdown-Fassung dieser Seite