# Authentification et scopes

## Tokens d’accès personnels

Créez des tokens dans l’application KolWrite (**Paramètres → Compte → Accès à l’API**).
Les tokens se présentent sous la forme `kol_...`, ne s’affichent qu’une fois lors
de leur création et agissent en **votre nom** : ils voient vos fichiers,
consomment vos crédits et respectent les limites de votre offre.

Envoyez le token de l’une ou l’autre manière — les deux sont équivalentes :

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

- **Expiration** : par défaut, les tokens n’expirent pas ; vous pouvez définir une
  durée de 7, 30 ou 90 jours, ou une date personnalisée lors de leur création.
- **Révocation** : révoquez n’importe quel token dans l’application (ou avec `DELETE
  /api/v1/api-keys/{id}` depuis une session ouverte). La révocation prend effet immédiatement.
- Les tokens ne peuvent jamais gérer d’autres tokens, supprimer votre compte ni
  accéder aux endpoints d’administration — quels que soient leurs scopes.

## Scopes

Un token ne peut appeler que les endpoints couverts par les scopes qui lui sont
accordés. Chaque opération de la [référence](/) indique le scope requis
(`x-required-scope` dans la [spécification OpenAPI](/openapi.json)).

| Scope | Autorisations |
|---|---|
| `files:read` | Répertorier et télécharger les fichiers, dossiers, médias et imports ; consulter l’utilisation du stockage |
| `files:write` | Importer des fichiers, enregistrer des médias, créer ou modifier des dossiers et des espaces de travail |
| `jobs:read` | Consulter le statut des jobs, leur position dans la file d’attente, leurs résultats et leurs artefacts |
| `jobs:write` | Créer et annuler des jobs (transcription, incrustation de sous-titres) ; réorganiser la file d’attente |
| `transcripts:read` | Consulter les transcriptions, les versions et les URL de téléchargement des exports |
| `transcripts:write` | Enregistrer de nouvelles versions de transcription et restaurer les précédentes |
| `ai:use` | Utiliser l’IA gérée par KolWrite (chat, embeddings, transcription rapide) ; consomme des crédits |
| `copilot:write` | Exécuter de l’IA facturée et enregistrer les échanges dans le Copilot général ou celui d’une transcription autorisée |
| `shares:read` | Répertorier et examiner les liens de partage publics |
| `shares:write` | Créer, mettre à jour, renouveler et révoquer des liens de partage publics |
| `devices:read` | Répertorier les sessions ouvertes sur les appareils |
| `devices:write` | Fermer les sessions sur les appareils |
| `account:read` | Consulter les feature flags et les préférences d’utilisation de l’application |
| `account:write` | Modifier les préférences d’utilisation de l’application |
| `billing:read` | Consulter le solde de crédits, le registre et les allocations |

Préréglages dans l’application : **Lecture seule** (tous les `*:read`),
**Automatisation** (`files:*`, `jobs:*`, `transcripts:read`, `billing:read`),
**Accès complet**.

## Erreurs de scope

Scope manquant sur un endpoint couvert :

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

Endpoint hors du périmètre accessible aux tokens publics :

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

Les deux renvoient HTTP 403. Les tokens non valides ou révoqués renvoient
HTTP 401 avec `invalid_api_key`.

## Crédits et facturation

Les jobs réservent des crédits lors de leur création, puis le montant est régularisé
à la fin ; les appels d’IA sont facturés selon le nombre de tokens utilisés.
Consultez les dépenses avec `billing:read` :

- `GET /api/v1/billing/balance`
- `GET /api/v1/billing/ledger`