Authentification et scopes
Tokens d’accès personnels
L’accès à l’API est en libre-service : dès que votre compte a acheté des crédits, activez-le dans Paramètres → Compte → Accès à l’API. Les appels consomment vos crédits.
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/balanceGET /api/v1/billing/ledger
Limites et dépenses
- Les crédits sont la limite ferme : les appels payants (tâches de transcription et proxy IA) consomment des crédits et, sans solde, renvoient HTTP 402
insufficient_credits. - Votre palier d’usage monte tout seul selon les crédits achetés et l’âge du compte (Start, Build, Scale, Established). Chaque palier fixe un plafond mensuel, des requêtes par minute et des requêtes simultanées par clé.
- Dans l’app, vous pouvez fixer un budget mensuel pour le compte et, par clé, un plafond mensuel, des adresses IP autorisées et une expiration. Au-delà d’un budget ou d’un plafond, les appels payants renvoient HTTP 402
api_monthly_budget_reachedouapi_key_cap_reached; trop de requêtes renvoient HTTP 429 avecRetry-After. - Une dépense inhabituelle vous envoie d’abord un e-mail ; seuls les pics extrêmes mettent une clé en pause, et vous pouvez la reprendre dans l’app. En renouvelant une clé, l’ancienne peut rester valide jusqu’à 7 jours.