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
`groupId` (path)	number	yes	Workgroup ID — a positive integer. List: `GET /v1/workgroups`

Request fields (body)

Field	Type	Required	Description
`userId`	number	yes	ID 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
`success`	boolean	`true` when the new owner is assigned and this is confirmed by re-reading the group
`data.groupId`	number	Workgroup ID
`data.ownerId`	number	ID 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
400	`INVALID_PARAMS`	`groupId` is not a positive integer, for example `15.7`
400	`MISSING_REQUIRED_FIELDS`	`userId` is missing or is not a positive integer. A `userIds` array instead of `userId` also returns this code
401	`MISSING_API_KEY`	`X-Api-Key` is not sent
401	`INVALID_API_KEY`	The key is not recognized — no such key exists on the platform
401	`TOKEN_MISSING`	The key has no Bitrix24 tokens
403	`SCOPE_DENIED`	The key lacks the `sonet_group` scope
403	`WRITE_BLOCKED_READONLY_KEY`	The key works in read-only mode
403	`BITRIX_ACCESS_DENIED`	The user the key acts on behalf of has no permission to change the owner of this group
404	`ENTITY_NOT_FOUND`	The group does not exist or is not visible to the user the key acts on behalf of
422	`BITRIX_ERROR`	Bitrix24 did not confirm the owner change
422	`BITRIX_ERROR`	Bitrix24 responded with success, but re-reading the group showed a different owner. Re-read the group before retrying
422	`BITRIX_ERROR`	Bitrix24 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
429	`RATE_LIMITED`	Request limit exceeded. Retry after the delay in the `Retry-After` header
502	`BITRIX_UNAVAILABLE`	Bitrix24 is unavailable or returned a response the endpoint cannot parse
503	`BITRIX_TIMEOUT`	Bitrix24 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