# Аутентификация и области доступа

## Персональные токены доступа

Создавайте токены в приложении KolWrite (**Настройки → Аккаунт → Доступ к
API**). Токены имеют вид `kol_...`, показываются только один раз при создании
и действуют от **вашего имени**: получают доступ к вашим файлам, расходуют
ваши кредиты и учитывают ограничения вашего тарифа.

Передать токен можно любым из двух способов — они равнозначны:

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

- **Срок действия**: по умолчанию токены бессрочны; при создании можно задать
  срок 7, 30 или 90 дней либо выбрать произвольную дату.
- **Отзыв**: отзовите любой токен в приложении (либо выполните `DELETE
  /api/v1/api-keys/{id}` из сеанса, в котором выполнен вход). Изменение
  вступает в силу немедленно.
- Токены не могут управлять другими токенами, удалять ваш аккаунт или
  обращаться к административным эндпоинтам независимо от предоставленных
  областей доступа.

## Области доступа

Токен может обращаться только к эндпоинтам, которые входят в предоставленные
ему области доступа. Для каждой операции в [справочнике](/) указана
необходимая область доступа (`x-required-scope` в
[спецификации OpenAPI](/openapi.json)).

| Область доступа | Разрешения |
|---|---|
| `files:read` | Просмотр и скачивание файлов, папок, медиафайлов и загрузок; просмотр использования хранилища |
| `files:write` | Загрузка файлов, регистрация медиафайлов, создание и обновление папок и рабочих пространств |
| `jobs:read` | Просмотр статуса задачи, позиции в очереди, результатов и артефактов задачи |
| `jobs:write` | Создание и отмена задач (расшифровка, наложение субтитров); изменение порядка очереди |
| `transcripts:read` | Просмотр расшифровок, версий и URL для скачивания экспорта |
| `transcripts:write` | Сохранение новых версий расшифровок и восстановление предыдущих |
| `ai:use` | Использование управляемого ИИ KolWrite (чат, эмбеддинги, быстрая расшифровка); расходует кредиты |
| `copilot:write` | Запуск тарифицируемого ИИ и сохранение диалогов в общем Copilot или Copilot разрешённой расшифровки |
| `shares:read` | Просмотр списка публичных ссылок общего доступа и сведений о них |
| `shares:write` | Создание, обновление, ротация и отзыв публичных ссылок общего доступа |
| `devices:read` | Просмотр сеансов на устройствах, где выполнен вход |
| `devices:write` | Завершение сеансов на устройствах |
| `account:read` | Просмотр флагов функций и настроек интерфейса приложения |
| `account:write` | Изменение настроек интерфейса приложения |
| `billing:read` | Просмотр баланса кредитов, журнала операций и начислений |

Предустановленные наборы в приложении: **Только чтение** (все `*:read`),
**Автоматизация** (`files:*`, `jobs:*`, `transcripts:read`, `billing:read`),
**Полный доступ**.

## Ошибки областей доступа

Не хватает области доступа для поддерживаемого эндпоинта:

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

Эндпоинт недоступен для публичных токенов:

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

В обоих случаях возвращается HTTP 403. Для недействительных или отозванных
токенов возвращается HTTP 401 с кодом `invalid_api_key`.

## Кредиты и оплата

При создании задачи кредиты резервируются, а после её завершения производится
окончательный расчёт; вызовы ИИ тарифицируются по количеству использованных
токенов. Проверяйте расходы с областью доступа `billing:read`:

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