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

Transfer group ownership

PUT /v1/workgroups/:groupId/owner

Assigns a new owner to a workgroup. The new owner can also be a user who is not in the group: they are added to it right away with the owner role.

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
FielduserId Typenumber Requiredyes DescriptionID of the new owner — a positive integer. One user, not an array. List: GET /v1/users

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/workgroups/157/owner" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": 93}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/workgroups/157/owner" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": 93}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/157/owner', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 93 }),
})

const body = await res.json()
console.log('Group owner:', body.data.ownerId)

JavaScript — OAuth application

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

const body = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the new owner is assigned and this is confirmed by re-reading the group
Fielddata.groupId Typenumber DescriptionWorkgroup ID
Fielddata.ownerId Typenumber DescriptionID of the group owner after the call. Matches the userId sent

Response example

JSON 
{
  "success": true,
  "data": {
    "groupId": 157,
    "ownerId": 93
  }
}

Error response example

403 — after the transfer, the previous owner tries to change the owner again:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Insufficient permissions for the operation",
    "hint": "Bitrix24 reports an access-rights refusal for sonet_group.setowner, not a scope error. The Bitrix24 user this call runs as lacks access; ask a portal admin to grant it, or call under a user who has it.",
    "cause": "b24_permission",
    "method": "sonet_group.setowner",
    "fix": {
      "action": "grant_b24_rights",
      "via": "portal_admin"
    }
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiongroupId is not a positive integer, for example 15.7
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionuserId is missing or is not a positive integer. A userIds array instead of userId also returns this code
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 the owner of 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 DescriptionBitrix24 did not confirm the owner change
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 responded with success, but re-reading the group showed a different owner. Re-read the group before retrying
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the owner change, or the group re-read, and returned its own reason in error.message. Re-read the group before retrying: the owner may have already changed
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 before retrying: the owner may have already changed

Full list of common API errors — Errors.

Known specifics

  • The transfer may be irreversible for the caller. After the call, the previous owner stays in the group with the member role K and loses the right to change the owner — even if they are a Bitrix24 account administrator. A repeat call on their behalf, including one to take ownership back, gets 403 BITRIX_ACCESS_DENIED. Before transferring ownership, make sure your choice of new owner is final.
  • A successful response means a confirmed change. Before responding, the platform re-reads the group and compares ownerId with the userId sent, so 200 is returned only when the new owner is already saved.
  • The owner change shows up in the group chat as a join. The group chat receives a system message that the new owner joined the group, even if they were already a member. There is no separate message about the owner change.
  • The previous owner keeps the right to change the membership. They can still add and remove members with POST and DELETE /v1/workgroups/:groupId/users after the transfer, if their Bitrix24 account permissions allow it.

See also