## Folder access levels

`GET /v1/folders/access-levels`

Returns the folder access levels configured on the Bitrix24 account: the level ID, its system code and its name in the account language.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/folders/access-levels" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/folders/access-levels" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/access-levels', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
for (const level of body.data) console.log(level.code, level.title)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/access-levels', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
for (const level of body.data) console.log(level.code, level.title)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | array | Access levels of the Bitrix24 account |
| `data[].id` | number | Level ID on the Bitrix24 account. Not needed to grant access: [`POST /v1/folders/:id/shares`](/docs/entities/folders/shares) takes the level by name in the `access` field |
| `data[].code` | string | System code of the level: `disk_access_full` — full access, `disk_access_edit` — edit, `disk_access_read` — read |
| `data[].title` | string | Level name in the Bitrix24 account language |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": 79,
      "code": "disk_access_full",
      "title": "Full access"
    },
    {
      "id": 75,
      "code": "disk_access_edit",
      "title": "Edit"
    },
    {
      "id": 71,
      "code": "disk_access_read",
      "title": "Read"
    }
  ]
}
```

## Error response example

403 — the key lacks the `disk` scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "API key requires \"disk\" scope.",
    "hint": "This request needs the 'disk' scope, which the calling key does not carry. Add 'disk' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "disk",
    "keyScopes": ["task", "im"],
    "fix": {
      "action": "edit_key_scopes",
      "via": "cabinet"
    },
    "userMessage": "The app's API key lacks the “Drive” permission. You can add it in the key settings in the developer cabinet."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `TOKEN_MISSING` | The key's portal has no authorization tokens |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 422 | `DISK_ACCESS_LEVELS_REFUSED` | Bitrix24 returned the list of levels in an unexpected form |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request; the reason is in `message` |
| 429 | `RATE_LIMITED` | Request limit exceeded — wait 1-2 seconds and retry |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable. The method only reads data, so the call can be retried |

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

## Known specifics

**The `add` level is not in the list.** The method returns three levels, while folder access can be granted at four levels: `read`, `add`, `edit`, `full`.

**Match levels by `code`.** The `id` value is assigned by the Bitrix24 account. The `title` value depends on the account language: on an English-language account it is "Full access"; on an account in another language, the name is in that language.

**Read-only key.** The method only reads data, so a key in read-only mode calls it without restrictions.

## See also

- [Share a folder with a user](/docs/entities/folders/shares)
- [Get a folder](/docs/entities/folders/get)
- [Folders](/docs/entities/folders)