Для AI-агентов: markdown этой страницы — /docs-content/infra/access/access-list.md индекс документации — /llms.txt

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

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

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

Параметры

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

Примеры

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

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

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

Terminal 
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
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
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 придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — Список серверов
404 NOT_FOUND Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки
429 RATE_LIMITED Превышен общий лимит запросов платформы

Полный список общих ошибок API — Ошибки.

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

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

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