## Share a folder with a user

`POST /v1/folders/:id/shares`

Grants a Bitrix24 account user access to a folder at the selected level. Access takes effect immediately, before the user responds to the invitation.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `id` (path) | number | yes | Folder ID. List: `GET /v1/folders?parentId=X` |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `userId` | number | yes | ID of the Bitrix24 account user who receives access. List: `GET /v1/users` |
| `access` | string | yes | Access level: `read` — read access, `add` — add access, `edit` — edit access, `full` — full access. A numeric `id` from [`GET /v1/folders/access-levels`](/docs/entities/folders/access-levels) is not accepted |

## Examples

### curl — personal key

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

### curl — OAuth application

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

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/shares', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 8, access: 'read' }),
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Access granted, user verified:', body.meta.recipientVerified)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/shares', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 8, access: 'read' }),
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Access granted, user verified:', body.meta.recipientVerified)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` — access granted |
| `data.folderId` | number | Folder ID |
| `data.userId` | number | ID of the user who received access |
| `data.access` | string | Granted level: `read`, `add`, `edit` or `full` |
| `meta.recipientVerified` | boolean | `true` — before access was granted, the API verified that the user exists and is not dismissed. `false` — no check was made: the key has no `user`, `user_basic` or `user_brief` scope |

## Response example

Access granted — HTTP status `201 Created`:

```json
{
  "success": true,
  "data": {
    "folderId": 10741,
    "userId": 8,
    "access": "read"
  },
  "meta": {
    "recipientVerified": true
  }
}
```

## Error response example

409 — the user owns the storage that contains the folder:

```json
{
  "success": false,
  "error": {
    "code": "DISK_SHARE_NOT_CREATED",
    "message": "No access was granted: the recipient may own this storage."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_ID` | The folder `id` is not a positive integer |
| 400 | `MISSING_REQUIRED_FIELDS` | The `userId` or `access` field is missing |
| 400 | `INVALID_PARAMS` | `userId` is not a positive integer, or `access` is not one of `read`, `add`, `edit`, `full` |
| 400 | `INVALID_PARAMS` | The user is dismissed. Checked when the key has the `user`, `user_basic` or `user_brief` scope |
| 401 | `TOKEN_MISSING` | The key's portal has no authorization tokens |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode, and granting access changes portal data |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 refused to let the key owner grant access to this folder |
| 404 | `ENTITY_NOT_FOUND` | There is no folder with this `id` |
| 404 | `ENTITY_NOT_FOUND` | The user was not found. Checked when the key has the `user`, `user_basic` or `user_brief` scope |
| 409 | `DISK_SHARE_NOT_CREATED` | Access was not granted: the user owns the storage that contains the folder |
| 409 | `DISK_ALREADY_SHARED` | The user already has access to this folder. The level cannot be changed through the API |
| 422 | `DISK_SHARE_REFUSED` | Bitrix24 did not confirm that access was granted |
| 422 | `BITRIX_ERROR` | Bitrix24 refused to grant access; the reason is in `message` |
| 429 | `RATE_LIMITED` | Request limit exceeded — wait 1-2 seconds and retry |
| 502 | `DISK_OUTCOME_UNKNOWN` | The connection to Bitrix24 dropped after the request was sent. The outcome is unknown, and no retry was made. If access was granted, a repeat call returns `409 DISK_ALREADY_SHARED` |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or did not return the user's data during the check; access was not granted |

Full list of general API errors — [Errors](/docs/errors).

## Known specifics

**Invitation.** The user receives a notification inviting them to accept or decline the folder. The rights apply from the moment they are granted; accepting only connects the folder to the user's Drive. On Bitrix24 accounts with auto-connection, the folder is connected immediately.

**User check.** The check runs with the key owner's permissions: if the key owner cannot see the user in `GET /v1/users`, the response is `404`. Without the `user`, `user_basic` and `user_brief` scopes there is no check, and the rights may be assigned to a nonexistent user — verify `userId` yourself before the call.

**Access cannot be changed or revoked through the API.** Granting a level higher than the key owner's own level is not possible either.

**Storage types.** Access is granted to folders in user storages, group storages and the shared drive.

**Batch calls.** The method is not part of [`POST /v1/batch`](/docs/batch) — call it as a separate request.

## See also

- [Folder access levels](/docs/entities/folders/access-levels)
- [Get a folder](/docs/entities/folders/get)
- [Public link to a folder](/docs/entities/folders/public-link)
- [List users](/docs/entities/users/list)
- [Folders](/docs/entities/folders)