Как выпустить API-ключ и передать его в X-Api-Key, как права ключа сочетаются с правами владельца и как получить токен пользователя.
Обновлено 27.09.2026
API volrix.pm принимает два вида авторизации. **API-ключ** в заголовке X-Api-Key - для интеграций: он не требует пароля, ограничен набором скоупов и отзывается одной кнопкой. **Токен пользователя** в заголовке Authorization: Bearer - для действий от имени конкретного человека и для маршрутов, которые ключ не принимают.
Где находится: «Администрирование» → «Настройки продукта» → «Интеграции». Пункт меню виден при праве «Интеграции: Просмотр ключей» (integrations.read). Создавать и отзывать ключи может сотрудник с правом «Создание и отзыв ключей» (integrations.manage).
В таблице ключей видны «Префикс» (часть ключа до точки), «Название», «Права», «Статус» («Активен», «Истек» или «Отозван»), «Истекает» и «Использован». Кнопка «Использование» показывает число запросов по дням за 30 дней, кнопка «Отозвать» отключает ключ сразу и без возврата.
Скоупы и срок существующего ключа не редактируются. Чтобы изменить набор прав, выпустите новый ключ, переключите на него интеграцию и отзовите старый.
Те же действия доступны через API: GET и POST /api/v1/integrations/api-keys, POST .../{key_id}/revoke, GET .../{key_id}/usage (см. API: администрирование).
Ключ передается целиком в заголовке **X-Api-Key**:
curl --fail-with-body -sS \ -H "X-Api-Key: $VOLRIX_API_KEY" \ "https://ваш-адрес/api/v1/users?page_size=5"
Ключ действует от имени сотрудника, который его выпустил (владельца). При каждом запросе сервер проверяет по порядку:
С версии 0.110.6 скоупы ключа только сужают текущие права владельца и никогда их не расширяют. Если у владельца отобрали право или сменили роль, тот же ключ сразу начинает получать 403 на соответствующих маршрутах.
Выпускайте ключи от служебной учетной записи с минимальной ролью, а не от личной учетной записи администратора. Если владельца ключа заблокируют (например, при увольнении), все его ключи перестанут работать с ответом 401.
Скоуп записывается как коллекция:действие (users:read), право в роли - как коллекция.действие (users.read). Список коллекций и действий - в «Администрирование» → «Доступ» → «Роли и права» и в статье Каталог прав.
Токен пользователя нужен для маршрутов с пометкой «Только сессия»: личный профиль, задачи плана, проекты, организации и другие. Получите его входом по логину и паролю:
curl --fail-with-body -sS -c cookies.txt \ -H "Content-Type: application/json" \ -d '{"email": "ivanov@company.ru", "password": "..."}' \ "https://ваш-адрес/api/v1/auth/login"
{"access_token": "eyJhbGciOi...", "token_type": "bearer", "requires_2fa": false}
Передавайте access_token в заголовке Authorization. Проверить, под кем выполнен вход и какие права есть, можно так:
curl --fail-with-body -sS \ -H "Authorization: Bearer $VOLRIX_TOKEN" \ "https://ваш-адрес/api/v1/auth/me"
Ответ содержит профиль и список permissions вида projects.read. По умолчанию access-токен живет 30 минут, refresh - 7 дней (переменные ACCESS_TOKEN_EXPIRE_MINUTES и REFRESH_TOKEN_EXPIRE_DAYS сервера). Новый access-токен выдает POST /auth/refresh по cookie, при этом cookie заменяется новой; прежнюю использовать нельзя.
curl --fail-with-body -sS -b cookies.txt -c cookies.txt -X POST \ "https://ваш-адрес/api/v1/auth/refresh"
Завершает сессию POST /auth/logout с тем же Bearer-токеном. Остальные маршруты входа, профиля и 2FA - в статье API: вход, пользователи и роли.
Не храните пароль сотрудника в интеграции, если задачу решает ключ. Для автоматического обмена данными выпускайте ключ, вход по паролю оставьте для действий, которые должен совершить сам человек.
Создать ограниченный ключ и проверить отзыв
Какие права выдать владельцу ключа
Базовый адрес, списки и коды ответов