Поля и коды ошибок методов доступа

Когда применять

Когда пишете интеграцию или разбираете ответ кластера: нужен точный набор полей, тип параметра, уровень доступа и смысл кода. Пошаговые сценарии — в инструкциях по управлению пользователями, по ролям и привилегиям и по входу и сессиям; модель прав — в «Модели доступа vStack Center». Сокращение ВЦОД в таблицах ниже — виртуальный центр обработки данных, объект области видимости vdc_id.

Сводка методов

Пользователи

Метод	Параметры	Доступ	Что возвращает
user-list	нет	Cluster master	карту активных пользователей, ключ — строковый id
user-get	id	Cluster master	профиль одного пользователя
user-create	name, fullname	Cluster master	id созданной записи
user-delete	id	Cluster master	пустой data
user-set-password	id, password	себе — любой пользователь; чужой id — Cluster master	пустой data
user-unlock	id	Cluster master	id разблокированной записи
user-params-get	нет	текущий пользователь	сохранённый JSON-объект параметров
user-params-set	произвольный объект	текущий пользователь	пустой data

Роли пользователя и назначения

Метод	Параметры	Доступ	Что возвращает
user-role	нет	текущий пользователь	UID и authmap
user-roles	user_id, q	себе — любой; чужой user_id — Cluster master	карту «ВЦОД → роль», с ключом q — «ВЦОД → массив ролей»
user-roles-v2	user_id	привилегия View Own User Roles (7102); чужой user_id — View Any User Roles (7106)	карту «роль → scope-атрибуты»
user-roles-map	нет	Cluster master	всех пользователей с развёрнутыми назначениями
user-role-assign	user_id, vdc_id, role_id	Cluster master	пустой data
user-role-deassign	user_id, vdc_id, role_id	Cluster master	пустой data

Параметр vdc_id в user-role-assign обязателен для роли со scope-привязкой; в user-role-deassign он обязателен всегда. Флаг q в user-roles определяется по наличию ключа в params — значение не читается. Для user-roles-v2 флаг q не поддерживается.

Роли и привилегии

Метод	Параметры	Доступ	Что возвращает
role-list	нет	в каноне API не указан	все роли со scope_ids, creator и метками времени
role-get	id	глобальная роль с привилегией View Role Details (7114)	роль с полными privileges и scope_ids
role-scopes	id	привилегия View Role Scopes (7115)	scope-атрибуты роли с self_referencing = false
role-create	name, privileges, scope_ids	Cluster master	id созданной роли
role-set	id, name, remove_privileges, add_privileges, scope_ids	Cluster master	пустой data
role-delete	id	Cluster master	пустой data
role-privilege-list	нет	привилегия View Role Privileges (7108), выдана всем семи фиксированным ролям	карту «role_id → массив privilege_id»
privilege-list	нет	привилегия View Privileges (7107), выдана всем семи фиксированным ролям	реестр привилегий с категориями, scope и методами
privilege-categories	нет	привилегия View Privilege Categories (7109), выдана всем семи фиксированным ролям	карту «category_id → название»
privilege-scopes	нет	привилегия View Privilege Scopes (7110), выдана всем семи фиксированным ролям	справочник scope-атрибутов

Ограничения доступа учётной записи

Метод	Параметры	Доступ	Что возвращает
user-remote-list	user_id	Cluster master	массив разрешённых CIDR
user-remote-add	user_id, remote	Cluster master	пустой data
user-remote-delete	user_id, remote	Cluster master	пустой data
user-vhost-list	user_id	Cluster master	массив разрешённых vhost
user-vhost-add	user_id, vhost	Cluster master	пустой data
user-vhost-delete	user_id, vhost	Cluster master	пустой data

Сессия и параметры безопасности

Метод	Параметры	Доступ	Что возвращает
auth-logout	all	любой аутентифицированный пользователь над своими сессиями	{"result": true}
auth-security-settings-get	нет	любой авторизованный; состав полей зависит от роли	параметры пароля и блокировки
auth-security-settings-set	восемь полей политики, все необязательные	Cluster master	пустой data

Параметры с валидацией

Метод	Параметр	Тип	Обязателен	Ограничение
user-create	name	string	да	regex ^[A-Z,a-z,_-]{4,41}$
user-create	fullname	string	нет	—
user-delete	id	number	да	range(min=0); id < 10 запрещены
user-set-password	id	number	нет	по умолчанию — текущий пользователь
user-set-password	password	string	да	regex ^[\S]+$ плюс парольная политика
user-role-assign	user_id, role_id	number	да	range(min=0); user_id < 10 запрещены
user-remote-add	remote	string	да	CIDR IPv4 с маской 8–32 либо IPv6 с префиксом 16–128
user-vhost-add	vhost	string	да	длина 5–512
role-create	name	string	да	длина 1–64, уникальное
role-create	privileges	array<integer>	да	не пустой; без 7111–7113
role-create	scope_ids	array<integer>	нет	только атрибуты с self_referencing = false
role-set	id	integer	да	не меньше 10000
role-delete	id	integer	да	не меньше 10000
auth-security-settings-set	max_failed_attempts, failed_attempts_window_minutes, password_min_length	integer	нет	range(min=1)
auth-security-settings-set	lockout_duration_minutes	integer	нет	range(min=0)
auth-logout	all	boolean	нет	по умолчанию false

Поля профиля пользователя

Состав одинаков для user-get и для каждой записи в user-list.

Поле	Тип	Описание
id	integer	идентификатор пользователя
name	string	имя учётной записи
fullname	string | null	полное имя
created	integer	время создания, epoch
modified	integer | null	время последнего изменения, epoch
failed_login_attempts	integer	счётчик неудачных попыток входа
first_failed_at	integer | null	начало текущего окна подсчёта, epoch; null — неудачных попыток нет
locked_until	integer | null	до какого времени запись заблокирована, epoch; null — не заблокирована

Поля роли

Поле	Тип	Где приходит	Описание
id	integer	role-list, role-get	идентификатор роли
name	string	role-list, role-get	имя роли
scope_ids	integer[]	role-list, role-get	scope-атрибуты роли; пустой массив — привязки нет
privileges	integer[]	role-get	полный список привилегий роли
creator	integer | null	role-list, role-get	автор роли; null у фиксированных ролей
created_ts	integer	role-list, role-get	время создания, unix timestamp
modified_ts	integer | null	role-list, role-get	время последнего изменения; null — не менялась

Фиксированные роли платформы:

ID	Имя
1	Cluster Master
2	vDC Admin
3	vDC User
4	vDC Viewer
5	Resource Viewer
6	Security Admin
7	VM Developer

Поля привилегии и scope-атрибута

Запись реестра privilege-list:

Поле	Тип	Описание
id	number	идентификатор привилегии
name	string	название привилегии
category_id	number | null	категория; null — привилегия не привязана к категории
scope_ids	number[]	scope-атрибуты привилегии; пустой массив — привилегия глобальная
methods	string[]	имена JSON-RPC методов, которые требуют эту привилегию

Запись справочника privilege-scopes и role-scopes:

Поле	Тип	Описание
id	integer	идентификатор scope-атрибута
name	string	имя атрибута, например vdc_id или creator
self_referencing	boolean	true — значение генерируется из user_id (creator); false — берётся из назначений роли (vdc_id)

В ответе role-scopes поле self_referencing всегда false: self-referencing атрибуты в этот ответ не попадают.

Категории привилегий (privilege-categories): 1 — vDC, 2 — VM, 3 — Network, 4 — Edge, 5 — Storage, 6 — Node, 7 — Cluster, 8 — User, 9 — Misc, 10 — Auth, 11 — Security, 12 — User Interface, 13 — Unified Storage, 14 — OS Image Library, 15 — Backup.

примечание

Канон API перечисляет в примере ответа только первые десять категорий, в базе их пятнадцать: каждый новый домен привозит свою. Метод отдаёт справочник целиком, так что сверяйтесь с фактическим ответом кластера.

Роли пользователя: четыре формата ответа

Метод	Форма data	Когда удобнее
user-role	UID + authmap: массив объектов vdc_id, vdc_name, role_id, role_name, GI_account	клиенту нужно показать «кто я и где» одним вызовом
user-roles без q	карта «строковый vdc_id → role_id»	быстрая проверка одной роли на ВЦОД
user-roles с q	карта «строковый vdc_id → массив role_id»	у пользователя больше одной роли в ВЦОД
user-roles-v2	карта «role_id → scopes», внутри по каждому attr_id: is_global и ids	нужно понять, чем именно ограничена роль
user-roles-map	карта «строковый id пользователя → профиль + массив roles»	инвентаризация всех назначений кластера

Поля user-roles-v2:

Поле	Тип	Описание
data.<role_id>.scopes	object	ключи — строковые attr_id scope-атрибутов роли
data.<role_id>.scopes.<attr_id>.is_global	boolean	true — значений в назначениях нет, роль по атрибуту не ограничена
data.<role_id>.scopes.<attr_id>.ids	integer[]	значения атрибута из назначений, например список ВЦОД

Допустимые role_id фиксированных ролей: 1–7. Кастомные роли приходят в тех же ответах с идентификаторами от 10000.

Параметры безопасности

Поле	Тип	Кому видно в auth-security-settings-get
max_failed_attempts	integer	только Cluster master
failed_attempts_window_minutes	integer	только Cluster master
lockout_duration_minutes	integer	только Cluster master
password_min_length	integer	всем авторизованным
password_require_uppercase	boolean	всем авторизованным
password_require_lowercase	boolean	всем авторизованным
password_require_digits	boolean	всем авторизованным
password_require_special	boolean	всем авторизованным

Коды ошибок

Пользователи

Код	Сообщение	Методы
-403	Access denied	user-list, user-roles-map
-403	Access denied	user-roles
-22204	Empty param user_id	user-roles, user-roles-v2
-22205	Bad id param value	user-roles, user-roles-v2
-403	Access denied	user-create
-22505	Bad name param value	user-create
-22515	Failed to add an user	user-create
-22516	User with name '<name>' exists already	user-create
-403	Access denied	user-delete
-22606	Specified user was not found	user-delete
-22610	Build-it users removal prohibited	user-delete
-403	Access denied	user-set-password
-22712	Bad password	user-set-password
-22720	Specified user was not found	user-set-password
-22730…-22735, -22737	требования парольной политики	user-set-password
-403	Access denied	user-get
-22803	No param id	user-get
-22804	Empty param id	user-get
-22805	Bad id param value	user-get
-403	Access denied	user-unlock
-22906	Specified user was not found	user-unlock
-29030	No user with ID==<uid>	user-params-get
-34000	No params at all	user-params-set
-39030	No user with ID==<uid>	user-params-set

Назначение ролей

Код	Сообщение	Методы
-403	Access denied	user-role-assign
-22320	Build-it users management prohibited / роль уже назначена	user-role-assign
-403	Access denied	user-role-deassign
-22420	Specified user has no specified role assignment	user-role-deassign
-22421	Build-it users management prohibited	user-role-deassign

Роли и привилегии

Код	Сообщение	Методы
-22500	Access denied: only Cluster Master can create roles	role-create
-22501	Privileges list must not be empty	role-create
-22502	Role management privileges cannot be assigned to custom roles	role-create
-22503	Privilege ID not found	role-create
-22504	Scope ID not found	role-create
-22505	Self-referencing scope cannot be assigned to custom role	role-create
-22506	Role with name already exists	role-create
-22510	Access denied: only Cluster Master can edit roles	role-set
-22511	Cannot modify a fixed role	role-set
-22512	Role not found	role-set
-22513	Role management privileges cannot be assigned to custom roles	role-set
-22514	Privilege ID not found	role-set
-22515	Scope ID not found	role-set
-22516	Role with name already exists	role-set
-22517	Self-referencing scope cannot be assigned to custom role	role-set
-22520	Access denied: only Cluster Master can delete roles	role-delete
-22521	Cannot delete a fixed role	role-delete
-22522	Role not found	role-delete
-22530	Role not found	role-get
-22540	Role not found	role-scopes

Диапазон -225xx занят дважды: те же номера используют user-create и группа role-*. Например, -22505 означает «недопустимое имя пользователя» в user-create и «self-referencing scope запрещён» в role-create, а -22516 — занятое имя пользователя либо занятое имя роли. Трактуйте код по вызванному методу, а не по номеру.

Ограничения доступа учётной записи

Код	Сообщение	Методы
-403	Access denied	все шесть методов группы
-24504	user_id param has been ommited	user-remote-list
-24505	user_id param is NULL	user-remote-list
-24506	user_id param value is not numeric	user-remote-list
-24604	user_id param has been ommited	user-vhost-list
-24605	user_id param is NULL	user-vhost-list
-24606	user_id param value is not numeric	user-vhost-list
-24712	remote param value is not CIDR	user-remote-add
-24713	remote param has mask out of range 8..32	user-remote-add
-24714	User ID==<id> has remote <cidr> already	user-remote-add
-24715	Invalid CIDR syntax of remote param	user-remote-add
-24812	remote param value is not CIDR / vhost param has bad length	user-remote-delete, user-vhost-add
-24814	User ID==<id> has no remote <cidr> / has vhost <vhost> already	user-remote-delete, user-vhost-add
-24815	Invalid CIDR syntax of remote param	user-remote-delete
-24912	vhost param has bad length	user-vhost-delete
-24914	User ID==<id> has no vhost <vhost>	user-vhost-delete

Пара -24812, -24814 в каноне API указана и для user-remote-delete, и для user-vhost-add. Смысл читайте по вызванному методу.

Сессия и параметры безопасности

Код	Сообщение	Где встречается
-9494	No session token	любой вызов без params.auth.cookie
-11000	токен не найден среди активных сессий, просрочен или погашен	auth-logout и любой вызов с недействительным токеном
-125	Temp token expired or invalid	user-set-password через temp_token
-126	Method not allowed with temp token	любой вызов с temp_token, кроме user-set-password и auth-security-settings-get
-127	Temp token allows changing own password only	user-set-password через temp_token
-403	Access denied	auth-security-settings-set
-29101	Security settings not found	auth-security-settings-get
-29102	ошибка базы данных	auth-security-settings-get, auth-security-settings-set

Ограничения по идентификаторам

Диапазон	Что означает	Следствие
пользователи id < 10	встроенные учётные записи	нельзя удалять (-22610), нельзя менять назначения ролей (-22320, -22421)
роли id < 10000	фиксированные роли платформы	нельзя изменить (-22511) и удалить (-22521); creator — null
роли id ≥ 10000	кастомные роли	создаются role-create, удаляются каскадно вместе с назначениями
привилегии 7111–7113	управление ролями	кастомной роли не назначаются (-22502, -22513)

Пример: полный ввод пользователя в строй

{"jsonrpc": "2.0", "method": "user-create", "params": {"name": "ops_duty", "fullname": "Ops Duty"}, "id": "1"}

{"jsonrpc": "2.0", "method": "user-set-password", "params": {"id": 12, "password": "<пароль>"}, "id": "2"}

{"jsonrpc": "2.0", "method": "user-role-assign", "params": {"user_id": 12, "vdc_id": 10, "role_id": 2}, "id": "3"}

{"jsonrpc": "2.0", "method": "user-roles-map", "id": "4"}

Последний вызов — проверка: в его ответе у пользователя 12 должно появиться назначение с role_id: 2 и нужным vdc_id.