Fields and error codes for access methods

When to use this reference

Use this reference when writing an integration or interpreting a cluster response and you need the exact field set, parameter type, access level, and meaning of a code. For step-by-step procedures, see the guides on user management, on roles and privileges, and on sign-in and sessions; for the permission model, see vStack Center access model. VDC in the tables below stands for virtual data center, the object scoped by vdc_id.

Method summary

Users

Method	Parameters	Access	Returns
user-list	none	Cluster master	a map of active users, keyed by string id
user-get	id	Cluster master	a single user's profile
user-create	name, fullname	Cluster master	the created account's id
user-delete	id	Cluster master	empty data
user-set-password	id, password	own password: any user; another user's id: Cluster master	empty data
user-unlock	id	Cluster master	the unlocked account's id
user-params-get	none	current user	the saved JSON settings object
user-params-set	arbitrary object	current user	empty data

User roles and assignments

Method	Parameters	Access	Returns
user-role	none	current user	UID and authmap
user-roles	user_id, q	own roles: any user; another user's user_id: Cluster master	a VDC → role map; with the q key, a VDC → role array map
user-roles-v2	user_id	the View Own User Roles privilege (7102); another user's user_id: View Any User Roles (7106)	a role → scope attributes map
user-roles-map	none	Cluster master	all users with expanded assignments
user-role-assign	user_id, vdc_id, role_id	Cluster master	empty data
user-role-deassign	user_id, vdc_id, role_id	Cluster master	empty data

The vdc_id parameter in user-role-assign is required for a role with a scope binding; in user-role-deassign, it is always required. The q flag in user-roles is determined by the presence of the key in params; its value is not read. The q flag is not supported for user-roles-v2.

Roles and privileges

Method	Parameters	Access	Returns
role-list	none	not specified in the canonical API documentation	all roles with scope_ids, creator, and timestamps
role-get	id	a global role with the View Role Details privilege (7114)	the role with its complete privileges and scope_ids
role-scopes	id	the View Role Scopes privilege (7115)	the role's scope attributes with self_referencing = false
role-create	name, privileges, scope_ids	Cluster master	the created role's id
role-set	id, name, remove_privileges, add_privileges, scope_ids	Cluster master	empty data
role-delete	id	Cluster master	empty data
role-privilege-list	none	the View Role Privileges privilege (7108), granted to all seven fixed roles	a role_id → array of privilege_id map
privilege-list	none	the View Privileges privilege (7107), granted to all seven fixed roles	the privilege registry with categories, scopes, and methods
privilege-categories	none	the View Privilege Categories privilege (7109), granted to all seven fixed roles	a category_id → name map
privilege-scopes	none	the View Privilege Scopes privilege (7110), granted to all seven fixed roles	the scope attribute reference

Account access restrictions

Method	Parameters	Access	Returns
user-remote-list	user_id	Cluster master	an array of allowed CIDRs
user-remote-add	user_id, remote	Cluster master	empty data
user-remote-delete	user_id, remote	Cluster master	empty data
user-vhost-list	user_id	Cluster master	an array of allowed vhosts
user-vhost-add	user_id, vhost	Cluster master	empty data
user-vhost-delete	user_id, vhost	Cluster master	empty data

Session and security settings

Method	Parameters	Access	Returns
auth-logout	all	any authenticated user, for their own sessions	{"result": true}
auth-security-settings-get	none	any authorized user; the field set depends on the role	password and lockout settings
auth-security-settings-set	eight policy fields, all optional	Cluster master	empty data

Parameters with validation

Method	Parameter	Type	Required	Restriction
user-create	name	string	yes	regex ^[A-Z,a-z,_-]{4,41}$
user-create	fullname	string	no	—
user-delete	id	number	yes	range(min=0); id < 10 is prohibited
user-set-password	id	number	no	defaults to the current user
user-set-password	password	string	yes	regex ^[\S]+$ plus the password policy
user-role-assign	user_id, role_id	number	yes	range(min=0); user_id < 10 is prohibited
user-remote-add	remote	string	yes	IPv4 CIDR with a mask of 8–32 or IPv6 with a prefix of 16–128
user-vhost-add	vhost	string	yes	length 5–512
role-create	name	string	yes	length 1–64, unique
role-create	privileges	array<integer>	yes	nonempty; excludes 7111–7113
role-create	scope_ids	array<integer>	no	only attributes with self_referencing = false
role-set	id	integer	yes	at least 10000
role-delete	id	integer	yes	at least 10000
auth-security-settings-set	max_failed_attempts, failed_attempts_window_minutes, password_min_length	integer	no	range(min=1)
auth-security-settings-set	lockout_duration_minutes	integer	no	range(min=0)
auth-logout	all	boolean	no	defaults to false

User profile fields

The field set is the same for user-get and for each entry in user-list.

Field	Type	Description
id	integer	user identifier
name	string	account name
fullname	string | null	full name
created	integer	creation time, epoch
modified	integer | null	last modification time, epoch
failed_login_attempts	integer	failed sign-in attempt counter
first_failed_at	integer | null	start of the current counting window, epoch; null means no failed attempts
locked_until	integer | null	time until which the account is locked, epoch; null means not locked

Role fields

Field	Type	Returned by	Description
id	integer	role-list, role-get	role identifier
name	string	role-list, role-get	role name
scope_ids	integer[]	role-list, role-get	the role's scope attributes; an empty array means no binding
privileges	integer[]	role-get	the role's complete privilege list
creator	integer | null	role-list, role-get	the role's creator; null for fixed roles
created_ts	integer	role-list, role-get	creation time, unix timestamp
modified_ts	integer | null	role-list, role-get	last modification time; null means never modified

The platform's fixed roles:

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

Privilege and scope attribute fields

A privilege-list registry entry:

Field	Type	Description
id	number	privilege identifier
name	string	privilege name
category_id	number | null	category; null means the privilege is not assigned to a category
scope_ids	number[]	the privilege's scope attributes; an empty array means a global privilege
methods	string[]	names of JSON-RPC methods that require this privilege

A privilege-scopes and role-scopes reference entry:

Field	Type	Description
id	integer	scope attribute identifier
name	string	attribute name, such as vdc_id or creator
self_referencing	boolean	true means the value is generated from user_id (creator); false means it comes from role assignments (vdc_id)

In the role-scopes response, self_referencing is always false: self-referencing attributes are not included in this response.

Privilege categories (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.

note

The canonical API documentation lists only the first ten categories in its response example, while the database contains fifteen: each new domain adds its own category. The method returns the complete reference, so check the actual cluster response.

User roles: four response formats

Method	data format	When it is useful
user-role	UID + authmap: an array of objects with vdc_id, vdc_name, role_id, role_name, GI_account	the client needs to show "who I am and where" in a single call
user-roles without q	a string vdc_id → role_id map	quickly checking a single role per VDC
user-roles with q	a string vdc_id → array of role_id map	the user has more than one role in a VDC
user-roles-v2	a role_id → scopes map, containing is_global and ids for each attr_id	determining exactly how the role is restricted
user-roles-map	a string user id → profile + roles array map	taking an inventory of all cluster assignments

Fields in user-roles-v2:

Field	Type	Description
data.<role_id>.scopes	object	keys are string attr_id values of the role's scope attributes
data.<role_id>.scopes.<attr_id>.is_global	boolean	true means there are no values in the assignments and the role is not restricted by the attribute
data.<role_id>.scopes.<attr_id>.ids	integer[]	attribute values from assignments, such as a list of VDCs

Valid role_id values for fixed roles are 1–7. Custom roles appear in the same responses with identifiers starting at 10000.

Security settings

Field	Type	Visible to in auth-security-settings-get
max_failed_attempts	integer	only Cluster master
failed_attempts_window_minutes	integer	only Cluster master
lockout_duration_minutes	integer	only Cluster master
password_min_length	integer	all authorized users
password_require_uppercase	boolean	all authorized users
password_require_lowercase	boolean	all authorized users
password_require_digits	boolean	all authorized users
password_require_special	boolean	all authorized users

Error codes

Users

Code	Message	Methods
-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	password policy requirements	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

Role assignment

Code	Message	Methods
-403	Access denied	user-role-assign
-22320	Build-it users management prohibited / role already assigned	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

Roles and privileges

Code	Message	Methods
-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

The -225xx range is used twice: user-create and the role-* group use the same numbers. For example, -22505 means "invalid user name" in user-create and "self-referencing scope prohibited" in role-create, while -22516 means either a user name or a role name is already in use. Interpret the code by the method called, rather than by the number alone.

Account access restrictions

Code	Message	Methods
-403	Access denied	all six methods in the group
-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

The canonical API documentation lists the pair -24812, -24814 for both user-remote-delete and user-vhost-add. Interpret their meaning by the method called.

Session and security settings

Code	Message	Where it occurs
-9494	No session token	any call without params.auth.cookie
-11000	the token is not found among active sessions, has expired, or has been invalidated	auth-logout and any call with an invalid token
-125	Temp token expired or invalid	user-set-password using temp_token
-126	Method not allowed with temp token	any call with temp_token except user-set-password and auth-security-settings-get
-127	Temp token allows changing own password only	user-set-password using temp_token
-403	Access denied	auth-security-settings-set
-29101	Security settings not found	auth-security-settings-get
-29102	database error	auth-security-settings-get, auth-security-settings-set

Identifier restrictions

Range	Meaning	Consequence
users id < 10	built-in accounts	cannot be deleted (-22610); role assignments cannot be changed (-22320, -22421)
roles id < 10000	the platform's fixed roles	cannot be modified (-22511) or deleted (-22521); creator is null
roles id ≥ 10000	custom roles	created with role-create; deletion cascades to their assignments
privileges 7111–7113	role management	cannot be assigned to a custom role (-22502, -22513)

Example: complete user setup

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

The last call is a check: its response must show an assignment for user 12 with role_id: 2 and the required vdc_id.