لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/sites/permissions.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Site permissions

PUT /v1/sites/:id/permissions

Replaces all access permissions of a site: after the call, the site keeps only the permissions you pass. To reset all permissions, use DELETE /v1/sites/:id/permissions.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionSite ID. List: GET /v1/sites
Parameterscope (query) Typestring Requiredno DescriptionSite type: KNOWLEDGE — knowledge base, GROUP — workgroup site, MAINPAGE — home page. Omit the parameter for all other sites

Request fields (body)

Field Type Required Description
Fieldrights Typeobject Requiredyes DescriptionSite permissions: the key is an access code, the value is an array of operations. At least one access code is required
Fieldrights.<access code> Typestring[] Requiredyes DescriptionOperations for the access code: read — view, edit — edit, sett — change settings, public — publish, delete — delete, denied — access denied. An empty array is accepted. The access code is a non-empty string, for example U1317 for the employee with ID 1317 from GET /v1/users, or AU

No other fields are accepted in the body.

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/sites/42/permissions" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rights": {"U1317": ["read", "edit"]}}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/sites/42/permissions" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rights": {"U1317": ["read", "edit"]}}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/42/permissions', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rights: { U1317: ['read', 'edit'] } }),
})
const body = await res.json()

if (body.success && body.data.updated) {
  console.log('Site permissions replaced')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/42/permissions', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rights: { U1317: ['read', 'edit'] } }),
})
const body = await res.json()

if (body.success && body.data.updated) {
  console.log('Site permissions replaced')
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue — the permissions were replaced
Fielddata.updated Typeboolean DescriptionAlways true: Bitrix24 confirmed the permissions replacement

Response example

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

Error response example

400 — the body has no rights, or an empty object was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "rights must be a non-empty access-code dictionary; use DELETE to clear all rights"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body has no rights, or rights is an empty object or not an object
HTTP400 CodeINVALID_PARAMS DescriptionThe body has fields other than rights. The error message is Only rights is accepted
HTTP400 CodeINVALID_PARAMS DescriptionAn access code is an empty string, a value is not an array, or the array holds an operation outside read, edit, sett, public, delete, denied
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer
HTTP400 CodeINVALID_SCOPE Descriptionscope is not one of KNOWLEDGE, GROUP, MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo site with this id exists, or it is not visible to the key. A knowledge base, workgroup site or home page requires the scope parameter
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key does not belong to a Bitrix24 account administrator, or the Bitrix24 plan does not include extended site permissions
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is unavailable on the Bitrix24 account
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the permissions replacement or rejected the site operation
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

  • Assigned permissions cannot be verified through the API. No method reads site permissions. GET /v1/sites/:id/my-permissions shows only the operations of the key's user: for a Bitrix24 account administrator it lists all six operations regardless of the assigned permissions.

See also