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

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

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

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

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

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

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

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

Область доступа	Разрешения
`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), Полный доступ.

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

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

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

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

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

Markdown-версия этой страницы