user_roles_set

Set exactly which roles a member has. The list you send replaces the old one, so include every role the member should keep.

Request

{
  "cmd": "user_roles_set",
  "user": "alice",
  "roles": ["moderator", "photography", "user"]
}

Field	Type	Required	Description
user	string	Yes	Username or user ID. Matching ignores letter case and a leading @.
roles	string[]	Yes	Role names, at least one. IDs are not accepted. Duplicates are dropped. The order is saved as sent, and the first role with a color sets the member’s name color.

Response

The reply is a user_roles_get frame, not user_roles_set:

{
  "cmd": "user_roles_get",
  "user": "alice",
  "roles": ["moderator", "photography", "user"],
  "color": "#FFFF00",
  "gradient": "#FFFF00"
}

See user_roles_get for the fields.

• Every other authenticated connection receives the same frame.
• If the change alters which channels the member can see, each of their sessions receives a fresh channels_get frame.
• If the change gives or removes manage_users, the member’s sessions receive user_connect or user_disconnect frames for hidden members, since that permission lets them see invisible users.

The change is recorded in the audit log.

Permissions

Requires manage_roles. It is blocked while you are timed out.

Only the roles being added or removed are checked, not the member’s own rank. The server owner can add or remove any role except owner. Everyone else must pass these checks for each added or removed role:

• The role isn’t owner, admin, or user.
• The role ranks below your highest role. A lower position is a higher rank.
• You hold every permission the role grants, unless you have administrator. Without administrator, you can’t give or take a role that grants owner or administrator.

Nobody can remove the owner role with this command.

Errors

val	When
Role '<name>' does not exist	An entry in roles isn’t a role name.
User not found	No account matches user.
Cannot assign role '<name>': <reason>	You may not add this role. <reason> is one of the hierarchy errors below.
Cannot remove 'owner' role	The member has owner and it’s missing from roles.
Cannot remove role '<name>': <reason>	You may not remove this role. <reason> is one of the hierarchy errors below.
Unable to save users	The server could not write the change to storage.
Validation message	user is missing or blank, or roles is missing, empty, or contains a non-string.

The <reason> text is one of:

• Cannot manage protected role '<name>'
• Cannot manage roles at or above your position
• Cannot assign '<permission>' — you don't have this permission yourself
• Role '<name>' not found, when removing a role name that no longer exists

See also

• user_roles_get
• role_reorder
• Roles and permissions