Share a folder with a user

POST /v1/folders/:id/shares

Access takes effect immediately, before the recipient accepts. You cannot change its level or revoke it through the API; use the Bitrix24 interface.

The recipient receives an Accept/Decline notification. Acceptance only connects the folder to their Disk; some portals connect it automatically. You cannot grant more access than you hold. userId is a portal user id, not a Vibe user id.

Parameters

Key scope: disk. READONLY keys cannot share. With user, user_basic or user_brief scope, existence and activity are checked by user.get before granting access. Without any of these scopes the check is skipped, meta.recipientVerified=false. Bitrix24 itself can grant rights to a nonexistent user; verify the recipient yourself when using a disk-only key.

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/folders/42/shares" -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"userId":8,"access":"read"}'

curl — application key

curl -X POST "https://vibecode.bitrix24.com/v1/folders/42/shares" -H "X-Api-Key: YOUR_APP_KEY" -H "Content-Type: application/json" -d '{"userId":8,"access":"read"}'

JavaScript — personal key

const response = await fetch("https://vibecode.bitrix24.com/v1/folders/42/shares", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ userId: 8, access: "read" }),
});
const data = await response.json();

JavaScript — application key

const response = await fetch("https://vibecode.bitrix24.com/v1/folders/42/shares", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_APP_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ userId: 8, access: "read" }),
});
const data = await response.json();

Response

{"success":true,"data":{"folderId":42,"userId":8,"access":"read"},"meta":{"recipientVerified":true}}

HTTP 201 confirms creation.

Response fields

Limitations and errors

409 DISK_SHARE_NOT_CREATED: nothing was granted, for example to the storage owner. 409 DISK_ALREADY_SHARED: an invitation already exists, including when attempting to change its level. 400 INVALID_PARAMS: malformed recipient/access or inactive user; 404 ENTITY_NOT_FOUND: folder or checked recipient absent. 403: insufficient permissions, unsupported storage type or unavailable disk_folder_sharing feature. Native business errors are 422. Rights are granted only on user/group/common storages. No automatic write retries; an unknown 502 outcome requires reading state first. Not supported in batch.

Use access names rather than ids from access-levels.

Bitrix24 method: disk.folder.shareToUser, taskName=disk_access_<access>.

400 — malformed recipient or access:

{"success":false,"error":{"code":"INVALID_PARAMS","message":"Invalid parameters."}}