# 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](/openapi.json)).

| 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:

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

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

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