## Список доступа

`GET /v1/infra/servers/:id/access`

Возвращает список пользователей и отделов Битрикс24 с доступом к приложению. Применяется, когда [`accessPolicy`](./access-policy.md) установлено в `NAMED_USERS` (список пользователей) или `DEPARTMENT` (список отделов). Работает только для BLACKHOLE-серверов. При `OWNER_ONLY`, `PORTAL`, `AUTHENTICATED`, `PUBLIC` списки в базе сохраняются, но не применяются.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера |

## Примеры

### curl — личный ключ

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access
```

### curl — OAuth-приложение

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data } = await res.json()

console.log(`Пользователей: ${data.users.length}`)
console.log(`Отделов: ${data.departments.length}`)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.users` | array | Записи доступа пользователей, отсортированные по `createdAt` (новые сверху) |
| `data.users[].id` | string (UUID) | ID записи в таблице — нужен для [`DELETE`](./access-delete.md) |
| `data.users[].userId` | string | ID пользователя Битрикс24 |
| `data.users[].userName` | string \| null | Имя пользователя (необязательное, заполняется при добавлении) |
| `data.users[].networkUserId` | string \| null | Network ID пользователя — заполняется асинхронно после добавления, используется для сопоставления при входе через Вайбкод-сессию |
| `data.users[].grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |
| `data.users[].createdAt` | string (ISO 8601) | Момент добавления |
| `data.departments` | array | Записи доступа отделов |
| `data.departments[].id` | string (UUID) | ID записи — нужен для [`DELETE`](./access-delete.md) |
| `data.departments[].departmentId` | string | ID отдела Битрикс24 |
| `data.departments[].departmentName` | string | Имя отдела (обязательное при добавлении) |
| `data.departments[].grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |
| `data.departments[].createdAt` | string (ISO 8601) | Момент добавления |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": "b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60",
        "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
        "userId": "243",
        "userName": "Катя Иванова",
        "networkUserId": "net_90126",
        "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
        "createdAt": "2026-04-20T10:15:00.000Z"
      }
    ],
    "departments": [
      {
        "id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
        "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
        "departmentId": "5",
        "departmentName": "Разработка",
        "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
        "createdAt": "2026-04-20T11:30:00.000Z"
      }
    ]
  }
}
```

## Пример ответа при ошибке

400 — сервер в режиме OPEN:

```json
{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Access lists are a Black Hole feature. Server is in OPEN mode — switch to BLACKHOLE via PATCH /v1/infra/servers/:id/mode first."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `NOT_FOUND` | Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **Обе коллекции отдаются независимо от текущей политики.** Можно вести список пользователей и список отделов параллельно, а переключать активную политику через [`PATCH /access-policy`](./access-policy.md) позже.
- **`networkUserId` заполняется асинхронно.** Первые секунды после [`POST /access`](./access-add.md) поле может быть `null` — затем фоновый запрос к Битрикс24 проставит Network ID (он нужен для Вайбкод-сессий, если пользователь входит в Вайбкод через Вайбкод-логин, а не через OAuth Битрикс24).
- **`grantedBy` — ID пользователя Вайбкод, не Битрикс24.** Соответствует `User.id` в базе платформы, не `userId` на портале Битрикс24. Если запись создана из UI — это автор вызова. Если через API-ключ — владелец ключа.
- **Список не пагинируется и не имеет принудительного лимита.** Эндпоинт возвращает все записи `BlackHoleAccess` и `BlackHoleDepartment` для сервера. На практике количество — десятки записей: список пополняется вручную через [`POST /access`](./access-add.md).

## Смотрите также

- [Добавить пользователя/отдел](./access-add.md)
- [Удалить запись](./access-delete.md)
- [Политика доступа](./access-policy.md)
- [Поиск пользователей Битрикс24](./b24-users.md)