Главная / Документация / APIAPI: вход, пользователи и ролиМаршруты входа, учетных записей, сотрудников, ролей и личного профиля volrix.pm: права, параметры, тела запросов и примеры синхронизации.Обновлено 27.09.2026Группа отвечает за то, кто работает в системе и что ему разрешено: вход и сессия, учетные записи (/users), карточки сотрудников (/people), роли и их права (/admin/roles), профиль и двухфакторная аутентификация текущего пользователя (/me). Типовая задача интеграции - синхронизация с кадровой системой: завести нового сотрудника, выдать роли, заблокировать уволенного.**Сотрудник и учетная запись.** Карточка сотрудника (/people) - это человек в оргструктуре: должность, подразделение, руководитель, центр компетенций. Учетная запись (/users) - возможность входить в систему: email, роли, блокировка, сброс пароля и 2FA. POST /people по умолчанию создает и вход (поле has_login, по умолчанию true); передайте has_login: false, если человеку вход не нужен.Базовый адрес, формат ответов и коды ошибок описаны в статье API: адрес, первый запрос и ответы, выпуск ключа и вход под пользователем - в статье API: вход, токен и API-ключи. В примерах ключ лежит в переменной окружения VOLRIX_API_KEY, токен пользователя - в VOLRIX_TOKEN.Типовой сценарий: синхронизация с кадровой системой

Найдите сотрудника GET /api/v1/people?search=Иванов (скоуп employees:read). Ответ - массив карточек, фильтры is_active, has_login и role помогают сузить выборку.

Создайте, если его нет POST /api/v1/people с телом PersonCreate (employees:create). Обязательны full_name и email; roles - список кодов ролей.

Узнайте коды ролей GET /api/v1/admin/roles (roles:read) вернет роли с кодами. Коды передаются в поле roles.

Обновите роли PUT /api/v1/people/{person_id}/roles с телом {"roles": [...]} (employees:update) или PUT /api/v1/users/{user_id}/roles с массивом кодов (users:update_roles). Список заменяется целиком.

Заблокируйте уволенного POST /api/v1/users/{user_id}/block (users:block). Вернуть доступ - POST .../unblock (users:unblock).

Примеры запросовПоиск учетных записей по имени или email (скоуп users:read). Ответ - страница с items, total, page, page_size и pages:curl --fail-with-body -sS \ -H "X-Api-Key: $VOLRIX_API_KEY" \ "https://ваш-адрес/api/v1/users?search=ivanov&is_active=true&page_size=50"Создание сотрудника с входом и ролью (скоуп employees:create):curl --fail-with-body -sS -X POST \ -H "X-Api-Key: $VOLRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"full_name": "Петров Петр", "email": "petrov@company.ru", "position": "Инженер", "roles": ["user"]}' \ "https://ваш-адрес/api/v1/people"Маршруты /me и /auth/me работают только в сессии самого пользователя: ключ не является пользователем, и эти маршруты его не принимают.МаршрутыКак читать колонку «Доступ»: **скоуп вида users:read** - маршрут принимает API-ключ, если в ключе есть этот скоуп, а у сотрудника, выпустившего ключ, есть такое же право в роли (users.read). Если скоупов несколько через «+», нужны все. **Только сессия** - нужен заголовок Authorization: Bearer, API-ключ получит 403. **Без авторизации** - заголовки не нужны. Доступ к конкретному объекту (участие в проекте, права на папку Диска) сервер проверяет дополнительно. Пути в таблицах указаны полностью, от корня сервера.Вход и сессия

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

POST /api/v1/auth/login

Нет | Тело: application/json: LoginRequest

Без авторизации

200: TokenResponse

POST /api/v1/auth/refresh

refresh_token [cookie]: string / null

Без авторизации

200: TokenResponse

POST /api/v1/auth/logout

Нет

Только сессия

200: object

GET /api/v1/auth/me

Нет

Только сессия

200: UserRead

POST /api/v1/auth/change-password

Нет | Тело: application/json: ChangePasswordRequest

Только сессия

204

POST /api/v1/auth/forgot-password

Нет | Тело: application/json: ForgotPasswordRequest

Без авторизации

204

POST /api/v1/auth/reset-password

Нет | Тело: application/json: ResetPasswordByTokenRequest

Без авторизации

204

GET /api/v1/auth/password-policy

Нет

users:update

200: PasswordPolicy

PUT /api/v1/auth/password-policy

Нет | Тело: application/json: PasswordPolicy

users:update

200: PasswordPolicy

GET /api/v1/auth/password-rules

Нет

Без авторизации

200: object

Учетные записи

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/users

page [query]: integer (default=1, min=1); page_size [query]: integer (default=20, min=1, max=100); search [query]: string / null; is_active [query]: boolean / null

users:read

200: object

POST /api/v1/users

Нет | Тело: application/json: UserCreate

users:create

201: UserRead

GET /api/v1/users/{user_id}

user_id [path обяз.]: string (uuid)

users:read

200: UserRead

PUT /api/v1/users/{user_id}

user_id [path обяз.]: string (uuid) | Тело: application/json: UserUpdate

users:update

200: UserRead

POST /api/v1/users/{user_id}/block

user_id [path обяз.]: string (uuid)

users:block

200: UserRead

POST /api/v1/users/{user_id}/unblock

user_id [path обяз.]: string (uuid)

users:unblock

200: UserRead

POST /api/v1/users/{user_id}/reset-password

user_id [path обяз.]: string (uuid) | Тело: application/json: PasswordResetRequest

users:reset_password

200: UserRead

POST /api/v1/users/{user_id}/send-password-reset

user_id [path обяз.]: string (uuid)

users:send_password_reset

200: object

POST /api/v1/users/{user_id}/reset-2fa

user_id [path обяз.]: string (uuid)

users:reset_2fa

200: UserRead

PUT /api/v1/users/{user_id}/roles

user_id [path обяз.]: string (uuid) | Тело: application/json: array[string]

users:update_roles

200: UserRead

Роли

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/admin/roles/catalog

Нет

roles:read

200: CollectionsCatalog

GET /api/v1/admin/roles

Нет

roles:read

200: array[RoleListItem]

POST /api/v1/admin/roles

Нет | Тело: application/json: RoleCreate

roles:create

201: app__schemas__role__RoleRead

GET /api/v1/admin/roles/{role_id}

role_id [path обяз.]: string (uuid)

roles:read

200: RoleWithPermissions

PUT /api/v1/admin/roles/{role_id}

role_id [path обяз.]: string (uuid) | Тело: application/json: RoleUpdate

roles:update

200: app__schemas__role__RoleRead

DELETE /api/v1/admin/roles/{role_id}

role_id [path обяз.]: string (uuid)

roles:delete

204

GET /api/v1/admin/roles/{role_id}/default-permissions

role_id [path обяз.]: string (uuid)

roles:read

200: array[PermissionPair]

PUT /api/v1/admin/roles/{role_id}/permissions

role_id [path обяз.]: string (uuid) | Тело: application/json: RolePermissionsUpdate

roles:update

200: RoleWithPermissions

GET /api/v1/roles/list

scope [query]: string (default=all)

Только сессия

200: object

Профиль и 2FA текущего пользователя

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/me/profile

Нет

Только сессия

200: object

PUT /api/v1/me/profile

Нет | Тело: application/json: MyProfileUpdate

Только сессия

200: object

GET /api/v1/me/activity

limit [query]: integer (default=50, min=1, max=200); offset [query]: integer (default=0, min=0)

Только сессия

200: object

POST /api/v1/me/avatar

Нет | Тело: multipart/form-data: Body_upload_my_avatar_api_v1_me_avatar_post

Только сессия

200: object

DELETE /api/v1/me/avatar

Нет

Только сессия

204

GET /api/v1/me/2fa/status

Нет

Только сессия

200: object

POST /api/v1/me/2fa/setup

Нет

Только сессия

200: TotpSetupResponse

POST /api/v1/me/2fa/verify

Нет | Тело: application/json: TotpVerifyRequest

Только сессия

200: object

POST /api/v1/me/2fa/disable

Нет | Тело: application/json: TotpDisableRequest

Только сессия

204

GET /api/v1/me/2fa/backup-codes/info

Нет

Только сессия

200: BackupCodesInfoResponse

POST /api/v1/me/2fa/backup-codes/regenerate

Нет

Только сессия

200: BackupCodesRegenerateResponse

Сотрудники

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/people

is_active [query]: boolean / null; has_login [query]: boolean / null; role [query]: string / null; search [query]: string / null; employees_only [query]: boolean / null (default=false)

employees:read

200: array[PersonListItem]

POST /api/v1/people

Нет | Тело: application/json: PersonCreate

employees:create

201: object

GET /api/v1/people/{person_id}

person_id [path обяз.]: string (uuid)

employees:read

200: object

PUT /api/v1/people/{person_id}

person_id [path обяз.]: string (uuid) | Тело: application/json: PersonUpdate

employees:update

200: object

PUT /api/v1/people/{person_id}/roles

person_id [path обяз.]: string (uuid) | Тело: application/json: PersonRolesUpdate

employees:update

200: object

Вход через Kerberos

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/auth/sso/status

Нет

Без авторизации

200: object

POST /api/v1/auth/sso/kerberos

Нет

Без авторизации

200: TokenResponse

Вход через OIDC

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/auth/sso/oidc/login

Нет

Без авторизации

200: object

GET /api/v1/auth/sso/oidc/callback

code [query]: string / null; state [query]: string / null; error [query]: string / null; error_description [query]: string / null

Без авторизации

200: object

Тела запросовПоля JSON и форм multipart из схемы сервера. «Да» - поле обязательно. Ссылка на другую схему (например, array[QCApproverInput]) означает вложенный объект с теми же полями.LoginRequest: POST /auth/login

Поле

Обязательно

Тип / значения

Ограничения

Да

string

minLength=1; maxLength=254

password

Да

string

totp_code

Нет

string / null

ChangePasswordRequest: POST /auth/change-password

Поле

Обязательно

Тип / значения

Ограничения

current_password

Да

string

new_password

Да

string

ForgotPasswordRequest: POST /auth/forgot-password

Поле

Обязательно

Тип / значения

Ограничения

Да

string (email)

ResetPasswordByTokenRequest: POST /auth/reset-password

Поле

Обязательно

Тип / значения

Ограничения

token

Да

string

new_password

Да

string

PasswordPolicy: PUT /auth/password-policy

Поле

Обязательно

Тип / значения

Ограничения

min_length

Нет

integer

default=8

require_digit

Нет

boolean

default=false

require_lower

Нет

boolean

default=false

require_upper

Нет

boolean

default=false

require_special

Нет

boolean

default=false

lockout_threshold

Нет

integer

default=5

lockout_window_minutes

Нет

integer

default=15

lockout_duration_minutes

Нет

integer

default=15

UserCreate: POST /users

Поле

Обязательно

Тип / значения

Ограничения

Да

string (email)

full_name

Да

string

password

Нет

string / null

roles

Нет

array[string]

default=[]

employee_id

Нет

string (uuid) / null

send_welcome_email

Нет

boolean

default=true

UserUpdate: PUT /users/{user_id}

Поле

Обязательно

Тип / значения

Ограничения

Нет

string (email) / null

full_name

Нет

string / null

roles

Нет

array[string] / null

employee_id

Нет

string (uuid) / null

PasswordResetRequest: POST /users/{user_id}/reset-password

Поле

Обязательно

Тип / значения

Ограничения

new_password

Да

string

RoleCreate: POST /admin/roles

Поле

Обязательно

Тип / значения

Ограничения

code

Да

string

minLength=2; maxLength=64; формат: строчные латинские буквы, цифры и _, первая - буква

label

Да

string

minLength=1; maxLength=255

description

Нет

string / null

RoleUpdate: PUT /admin/roles/{role_id}

Поле

Обязательно

Тип / значения

Ограничения

label

Нет

string / null

description

Нет

string / null

RolePermissionsUpdate: PUT /admin/roles/{role_id}/permissions

Поле

Обязательно

Тип / значения

Ограничения

permissions

Да

array[PermissionPair]

MyProfileUpdate: PUT /me/profile

Поле

Обязательно

Тип / значения

Ограничения

full_name

Нет

string / null

position

Нет

string / null

department

Нет

string / null

phone

Нет

string / null

birth_date

Нет

string (date) / null

passport_series

Нет

string / null

passport_number

Нет

string / null

passport_issued_by

Нет

string / null

passport_issue_date

Нет

string (date) / null

passport_dept_code

Нет

string / null

registration_address

Нет

string / null

inn

Нет

string / null

snils

Нет

string / null

Форма multipart: POST /me/avatar

Поле

Обязательно

Тип / значения

Ограничения

file

Да

string (binary)

TotpVerifyRequest: POST /me/2fa/verify

Поле

Обязательно

Тип / значения

Ограничения

code

Да

string

TotpDisableRequest: POST /me/2fa/disable

Поле

Обязательно

Тип / значения

Ограничения

password

Да

string

PersonCreate: POST /people

Поле

Обязательно

Тип / значения

Ограничения

birth_date

Нет

string (date) / null

passport_series

Нет

string / null

passport_number

Нет

string / null

passport_issued_by

Нет

string / null

passport_issue_date

Нет

string (date) / null

passport_dept_code

Нет

string / null

registration_address

Нет

string / null

inn

Нет

string / null

snils

Нет

string / null

full_name

Да

string

minLength=1; maxLength=255

Да

string (email)

position

Нет

string / null

department

Нет

string / null

personnel_number

Нет

string / null

phone

Нет

string / null

manager_id

Нет

string (uuid) / null

has_login

Нет

boolean

default=true

password

Нет

string / null

roles

Нет

array[string]

default=[]

staff_category

Нет

string

default="management"

competency_center_id

Нет

string (uuid) / null

PersonUpdate: PUT /people/{person_id}

Поле

Обязательно

Тип / значения

Ограничения

birth_date

Нет

string (date) / null

passport_series

Нет

string / null

passport_number

Нет

string / null

passport_issued_by

Нет

string / null

passport_issue_date

Нет

string (date) / null

passport_dept_code

Нет

string / null

registration_address

Нет

string / null

inn

Нет

string / null

snils

Нет

string / null

full_name

Нет

string / null

position

Нет

string / null

department

Нет

string / null

personnel_number

Нет

string / null

phone

Нет

string / null

manager_id

Нет

string (uuid) / null

is_active

Нет

boolean / null

staff_category

Нет

string / null

competency_center_id

Нет

string (uuid) / null

PersonRolesUpdate: PUT /people/{person_id}/roles

Поле

Обязательно

Тип / значения

Ограничения

roles

Да

array[string]

Вложенный объект PermissionPair

Поле

Обязательно

Тип / значения

Ограничения

collection

Да

string

action

Да

string

Если не получается

Что видно

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

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

У маршрута в таблице указано «Только сессия». Выполните его с заголовком Authorization: Bearer от имени сотрудника, см. вход под пользователем.

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

В ключе нет скоупа из колонки «Доступ». Скоупы после создания не меняются: выпустите новый ключ с нужным скоупом в «Администрирование» → «Настройки продукта» → «Интеграции» и отзовите старый.

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

У пользователя или у сотрудника, выпустившего ключ, нет названного права в роли (с 0.110.6 для ключа проверяются и скоуп, и право владельца). Добавьте право в роль: «Администрирование» → «Доступ» → «Роли и права».

422 при создании сотрудника

Не передано full_name или email, либо email не проходит проверку формата. Смотрите loc в ответе.

423 при входе «Слишком много неудачных попыток»

Учетная запись временно заблокирована политикой паролей. Дождитесь конца блокировки; порог и длительность - в GET /auth/password-policy.

429 при входе

Больше 5 попыток входа в минуту с одного адреса. Подождите время из заголовка Retry-After.

423 на POST, PUT, PATCH или DELETE, чтение работает

Нет действующей лицензии (в ответе license_status: expired, invalid, missing или mismatch). Изменения заблокированы до загрузки файла лицензии, см. Лицензия.

Сотрудники

Роли и доступы

Пароли и блокировка

Карточки, роли и участие в работеКак выдать права и проверить ограниченияПравила входа и порог блокировки

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

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