For AI agents: markdown of this page — /docs-content-en/workgroups/members/role.md documentation index — /llms.txt

Change member role

PATCH /v1/workgroups/:groupId/users

Assigns the moderator role to workgroup members or returns them to the member role. One role applies to all users in userIds at once.

Parameters

Parameter Type Required Description
ParametergroupId (path) Typenumber Requiredyes DescriptionWorkgroup ID — a positive integer. List: GET /v1/workgroups

Request fields (body)

Field Type Required Description
FielduserIds Typenumber[] Requiredyes DescriptionNon-empty array of group member IDs — positive integers. Group membership: GET /v1/workgroups/:groupId/users
Fieldrole Typestring Requiredyes DescriptionNew role: moderator or member. In the group membership they appear as E and K, respectively

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "role": "moderator"}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "role": "moderator"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/157/users', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93], role: 'moderator' }),
})

const body = await res.json()
if (!body.success && body.error.code === 'BITRIX_ERROR') {
  if (Array.isArray(body.error.processedUserIds)) {
    // Some roles may have already changed — changes are not rolled back
    console.log('Role changed:', body.error.processedUserIds)
    console.log('Role not changed:', body.error.skippedUserIds)
  } else {
    // The other 422: Bitrix24 refused the call, so the response has no arrays
    console.log('Bitrix24 refused:', body.error.message)
  }
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/157/users', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93], role: 'moderator' }),
})

const body = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the role is changed for all requested users
Fielddata.groupId Typenumber DescriptionWorkgroup ID
Fielddata.processedUserIds Typenumber[] DescriptionIDs of the users who got the new role. Duplicates in userIds collapse into one
Fielddata.skippedUserIds Typenumber[] DescriptionAlways an empty array in a successful response. If the role did not change for everyone, the response is 422 BITRIX_ERROR and both arrays move into error. That is the only response that carries them: the other 422 BITRIX_ERROR — a refusal from Bitrix24 itself — carries only its own message in error, with no processedUserIds and no skippedUserIds

Response example

JSON 
{
  "success": true,
  "data": {
    "groupId": 157,
    "processedUserIds": [93],
    "skippedUserIds": []
  }
}

Error response example

422 — role member requested: it changed for user 93 but not for the group owner 1:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.",
    "processedUserIds": [93],
    "skippedUserIds": [1]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiongroupId is not a positive integer, for example 15.7
HTTP400 CodeINVALID_PARAMS Descriptionrole is missing or is neither moderator nor member
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionuserIds is missing, empty or contains something other than positive integers
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not sent
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the sonet_group scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user the key acts on behalf of has no permission to change roles in this group
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe group does not exist or is not visible to the user the key acts on behalf of
HTTP422 CodeBITRIX_ERROR DescriptionThe role did not change for every user. error.processedUserIds lists the users whose role changed, error.skippedUserIds those whose role did not. A user is skipped if they already have this role or are the group owner
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the call and returned its own reason in error.message — for example, a role code it does not accept. This response carries no error.processedUserIds and no error.skippedUserIds — check that they are present before reading them, and re-read the membership before retrying
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response the endpoint cannot parse
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond in time. The response includes a Retry-After header. Re-read the group membership before retrying: the role may have already changed

Full list of common API errors — Errors.

Known specifics

  • A partial result is not rolled back. If some users are skipped, the response is 422, but the users in error.processedUserIds already have the new role. Check the outcome with GET /v1/workgroups/:groupId/users.
  • Repeating the call with the same role returns 422, not success. A user whose role already matches the requested one lands in skippedUserIds. To keep a repeated call from looking like an error, compare the roles in the group membership before the call.
  • This call does not change the owner's role. The owner is assigned by PUT /v1/workgroups/:groupId/owner.

See also