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

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

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

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