Assign Role to User

Post
/api/v1/roles.addUserToRole

Assign a role to a user. Optionally, you can set this role to a user for a specific room.
Permissions required:

  • access-permissions: Required to modify permissions for various roles
  • assign-admin-role: Permission to assign the admin role to other users

Changelog

Version Description
0.70.0 Added
Header parameters
X-User-Id
stringRequired

The authenticated user ID.

ExamplerbAXPnMktTFbNpwtJ
X-Auth-Token
stringRequired

The authenticated user token.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
Body parameters

By default, the three major room roles are available in Rocket.Chat are Owner, Leader, and Moderator. Creating custom roles is exclusively available on the Enterprise plan. Refer to Roles for more information.

Example 1
{
  "roleName": "auditor-log",
  "username": "test.fun",
  "roomId": "64adb09baa5ad4273bfc"
}
object
roleName
string Required

The role name. Alternatively, use the roleId parameter. Note:

  • For default roles, the role name and ID are the same. For custom roles, the name and ID are different.
  • If you are setting a custom role for a user, make sure to enter the custom role ID and not the role name.
  • The roleName parameter will be removed from 7.0.0. Use the roleId parameter instead. Refer to Roles for more information.
Exampleauditor-log
username
string Required

The user name.

Exampletest.fun
roomId
string

The ID of the room where the user should be assigned a role, if it is a room role.

Example4adb09baa5ad42
Responses
200

OK

Success Example
{
  "role": {
    "_id": "auditor-log",
    "scope": "Users",
    "description": "",
    "mandatory2fa": false,
    "name": "auditor-log",
    "protected": true,
    "_updatedAt": "2023-07-10T23:20:56.702Z"
  },
  "success": true
}
Expand All
object
role
object
_id
string
scope
string
description
string
mandatory2fa
boolean
name
string
protected
boolean
_updatedAt
string
success
boolean
400

Bad Request

Example 1
{
  "success": false,
  "error": "must have required property 'username' [error-invalid-role-properties]",
  "errorType": "error-invalid-role-properties"
}
Example 2
{
  "success": false,
  "error": "The required \"userId\" or \"username\" param provided does not match any users [error-invalid-user]",
  "errorType": "error-invalid-user"
}
Example 3
{
  "success": false,
  "error": "error-invalid-role-properties"
}
object
success
boolean
error
string
errorType
string
401

Unauthorized

Authorization Error
{
  "status": "error",
  "message": "You must be logged in to do this."
}
object
status
string
message
string