Главная / Документация / Настройки продуктаAPI-ключи: доступ внешних системКак выпустить API-ключ для 1С или другой системы: права ключа и владельца, срок, заголовок X-Api-Key, пример запроса, статистика и отзыв.Обновлено 24.10.2026Внешние системы - 1С, шина данных, скрипты выгрузки - обращаются к API volrix.pm по API-ключу, без пароля сотрудника. У каждого ключа свое название, набор прав (скоупов) и срок; ключ отзывается отдельно, не задевая остальные интеграции.«Администрирование» → «Настройки продукта» → «Интеграции», вкладка «API-ключи». На соседней вкладке «ЕИС» включается связь с zakupki.gov.ru для закупок в сделках - см. Закупки и ЕИС.Просмотр ключей и статистики - право integrations.read, создание и отзыв - integrations.manage. По умолчанию оба есть только у администратора системы. Реестр API-ключей: состояние и управление без показа полного секрета.

Реестр API-ключей: состояние и управление без показа полного секрета.

Как ключ получает доступКлюч действует от имени того, кто его создал (владельца). С версии 0.110.6 запрос с ключом проходит, только если выполнены все условия сразу:

Проверка

Ответ при отказе

Ключ существует, не отозван и не истек

401 «Недействительный API-ключ»

Учетная запись владельца активна

401 «Владелец API-ключа недоступен»

Метод API проверяет права по матрице ролей

403 «API-ключи не поддерживаются на этом эндпоинте»

У ключа есть скоуп этой операции

403 «API-ключ не имеет права (коллекция.действие)»

У владельца сейчас есть это право

403 «Недостаточно прав (коллекция.действие)»

Дальше действуют обычные проверки доступа к конкретным объектам - так же, как если бы запрос делал сам владелец. Что из этого следует на практике:

**Ключ не расширяет права.** Скоуп, которого нет у владельца, выбрать можно, но запрос с ним получит 403.

**Права владельца действуют сейчас, а не на момент выпуска.** Сменили роль владельцу - ключ сразу теряет снятые операции.

**Уход владельца останавливает его ключи.** Деактивация учетной записи - и все ее ключи получают 401. Для постоянных интеграций выпускайте ключи от служебной учетной записи с нужными правами и правом integrations.manage.

**Ключ администратора системы** ограничен только скоупами: у администратора есть все права.

**Смена SECRET_KEY в .env** делает недействительными все ключи - их придется выпустить заново.

**Не каждый метод принимает ключ.** Например, список проектов GET /api/v1/projects отбирает проекты по участию сотрудника, а не по праву из матрицы, и на ключ ответит 403. Проверьте нужные методы до передачи ключа интеграции.

Как выпустить ключ

Откройте окно Нажмите «Создать ключ» - откроется окно «Новый API-ключ».

Назовите ключ Поле «Название» обязательно, например «Интеграция с 1С». По названию ключ ищут в списке и в журнале аудита.

Выберите права В поле «Права (скоупы)» - список с поиском, сгруппированный по разделам, пункты вида «Пользователи: Просмотр». Это те же права, что в каталоге прав. Выберите только нужные операции: ключ без скоупов не пройдет ни на одном методе.

Задайте срок «Срок действия»: «Без срока», «30 дней», «90 дней» или «365 дней». После срока ключ перестает работать сам.

Сохраните секрет Нажмите «Создать». Откроется окно «Ключ создан» с предупреждением «Скопируйте ключ сейчас - он больше не будет показан. Хранится только его хеш.» Нажмите «Копировать», перенесите ключ в защищенное хранилище интеграции и нажмите «Готово».

Ключ выглядит как volrix_1a2b3c4d.<секрет>: первая часть до точки - префикс, по нему ключ виден в списке; для запроса нужен ключ целиком.Как передавать ключКлюч передается в заголовке X-Api-Key каждого запроса, только по HTTPS. Пример для ключа со скоупом «Пользователи: Просмотр»:curl -sS \ -H "X-Api-Key: volrix_1a2b3c4d.ВАШ_СЕКРЕТ" \ "https://pm.company.ru/api/v1/users?page=1&page_size=20"

Не передавайте в том же запросе заголовок Authorization: Bearer - при нем ключ не проверяется, запрос идет по токену входа.

Не кладите ключ в адрес запроса, открытый репозиторий, скриншот или журнал.

Методы и параметры описаны в разделе API: начало работы, способы входа - в Авторизации API.

Список ключей

Колонка

Что показывает

«Префикс»

Начало ключа до точки - чтобы узнать ключ, не раскрывая секрет.

«Права»

Значок «N прав»; при наведении - полный список скоупов.

«Статус»

«Активен», «Истек» или «Отозван».

«Истекает»

Дата окончания срока; пусто - без срока.

«Использован»

Время последнего запроса с этим ключом.

Кнопка «Использование» в строке показывает график запросов по дням: «За последние 30 дней - всего запросов: N». В счетчик попадают и запросы, отклоненные из-за нехватки скоупа. Кнопка «Отозвать» открывает окно «Отзыв ключа» с текстом «Действие необратимо, интеграции с этим ключом перестанут работать.» Отозванный ключ остается в списке для истории; выпуск и отзыв записываются в журнал аудита. Изменить скоупы или срок у существующего ключа нельзя - только выпустить новый.Замена ключа без остановки интеграции

Выпустите новый ключ С тем же набором прав и новым сроком.

Переключите интеграцию Замените ключ в настройках внешней системы и проверьте несколько рабочих запросов.

Отзовите старый Нажмите «Отозвать» у прежнего ключа и убедитесь, что запрос с ним получает 401, а в «Использовании» старого ключа новые запросы не появляются.

SwaggerКнопка «Открыть Swagger» ведет на /api/docs - интерактивный справочник методов вашей установки. Он опубликован, только если в .env задано EXPOSE_API_DOCS=true; по умолчанию справочник выключен и адрес отвечает 404. В закрытом контуре его обычно включают на время разработки интеграции.Если не получается

Что видно

Причина и что сделать

401 «Не авторизован»

Заголовок не дошел: проверьте имя X-Api-Key и что прокси между системами его не вырезает.

401 «Недействительный API-ключ»

Ключ скопирован не полностью (нужны обе части вокруг точки), отозван, истек или в .env сменился SECRET_KEY. Выпустите новый ключ.

401 «Владелец API-ключа недоступен»

Учетная запись создателя деактивирована. Выпустите ключ от активной служебной учетной записи.

403 «API-ключи не поддерживаются на этом эндпоинте»

Этот метод проверяет доступ не по матрице прав, ключ на нем не работает. Используйте другой метод или обратитесь к поставщику.

403 «API-ключ не имеет права (users.read)»

У ключа нет скоупа. Добавить его к существующему ключу нельзя: выпустите новый с нужным набором и отзовите старый.

403 «Недостаточно прав (users.read)»

Скоуп есть, но права нет у владельца. Выдайте право его роли в разделе Роли и права или выпустите ключ от другой учетной записи.

422 «Недопустимые скоупы: ...»

При создании через API передан скоуп не из каталога прав. Используйте формат коллекция:действие из каталога.

«Открыть Swagger» дает 404

Справочник выключен: EXPOSE_API_DOCS=false.

Полный ключ потерян

Прочитать его повторно нельзя. Выпустите новый, переключите интеграцию и отзовите старый.

Авторизация API

API: начало работы

Роли и права

Токены входа и API-ключи в запросах.Структура API и первые запросы.Права владельца, которыми ограничен ключ.

Интеграции и REST API

Функциональная карта