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).

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 :

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

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

Version Markdown de cette page