Autenticación y ámbitos

Tokens de acceso personal

Crea tokens en la aplicación KolWrite (Ajustes → Cuenta → Acceso a la API). Los tokens tienen el formato kol_..., se muestran una sola vez al crearlos y actúan en tu nombre: pueden ver tus archivos, consumir tus créditos y respetan los límites de tu plan.

Envía el token de cualquiera de estas formas; ambas son equivalentes:

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

Caducidad: los tokens no caducan de forma predeterminada; al crearlos, puedes establecer 7, 30 o 90 días, o una fecha personalizada.
Revocación: revoca cualquier token en la aplicación (o mediante DELETE /api/v1/api-keys/{id} desde una sesión iniciada). El cambio surte efecto de inmediato.
Los tokens nunca pueden gestionar otros tokens, eliminar tu cuenta ni acceder a endpoints administrativos, con independencia de sus ámbitos.

Ámbitos

Un token solo puede llamar a los endpoints cubiertos por los ámbitos que tenga concedidos. Cada operación de la referencia indica el ámbito que requiere (x-required-scope en la especificación OpenAPI).

Ámbito	Concede
`files:read`	Listar y descargar archivos, carpetas, contenido multimedia y subidas; consultar el uso del almacenamiento
`files:write`	Subir archivos, registrar contenido multimedia y crear o actualizar carpetas y espacios de trabajo
`jobs:read`	Consultar el estado, la posición en la cola, los resultados y los artefactos de los trabajos
`jobs:write`	Crear y cancelar trabajos (transcripción e incrustación de subtítulos); reordenar la cola
`transcripts:read`	Consultar transcripciones, versiones y URL de descarga de exportaciones
`transcripts:write`	Guardar versiones nuevas de las transcripciones y restaurar versiones anteriores
`ai:use`	Usar la IA gestionada de KolWrite (chat, embeddings y transcripción rápida); consume créditos
`copilot:write`	Ejecutar IA medida y guardar turnos en el Copilot general o en el Copilot de una transcripción autorizada
`shares:read`	Listar e inspeccionar enlaces públicos para compartir
`shares:write`	Crear, actualizar, rotar y revocar enlaces públicos para compartir
`devices:read`	Listar las sesiones iniciadas en dispositivos
`devices:write`	Cerrar las sesiones de los dispositivos
`account:read`	Consultar los indicadores de funciones y las preferencias de experiencia de la aplicación
`account:write`	Actualizar las preferencias de experiencia de la aplicación
`billing:read`	Consultar el saldo de créditos, el libro de movimientos y las concesiones

Ajustes predefinidos de la aplicación: Solo lectura (todos los *:read), Automatización (files:*, jobs:*, transcripts:read, billing:read) y Acceso completo.

Errores de ámbito

Falta un ámbito en un endpoint cubierto:

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

Endpoint fuera de la superficie disponible para tokens públicos:

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

Ambos casos devuelven HTTP 403. Los tokens no válidos o revocados devuelven HTTP 401 con invalid_api_key.

Créditos y facturación

Los trabajos reservan créditos al crearse y liquidan el importe al finalizar; las llamadas de IA se contabilizan según el uso de tokens. Consulta el gasto con billing:read:

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

Versión Markdown de esta página