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

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-ключ
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`.

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

Добавить пользователя/отдел — POST /v1/infra/servers/:id/access.
Удалить запись — DELETE /v1/infra/servers/:id/access/:accessId (здесь и используется id из ответа).
Политика доступа — переключить NAMED_USERS / DEPARTMENT.
Поиск пользователей Битрикс24 — найти userId.

Добавить пользователя или отдел

POST /v1/infra/servers/:id/access

Добавляет запись доступа к BLACKHOLE-серверу: конкретного пользователя Битрикс24 (при политике NAMED_USERS) или отдел (при политике DEPARTMENT). Политика при этом не меняется автоматически — смените её через `PATCH /access-policy` отдельно, если ещё не переключали. Дубликаты (тот же userId или departmentId на том же сервере) возвращают 409 ALREADY_EXISTS.

Параметры

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

Поля запроса (body)

Поле	Тип	Обяз.	Описание
`type`	string	да	`user` — добавить пользователя, `department` — добавить отдел
`userId`	string	да (для `type: "user"`)	ID пользователя Битрикс24. Ищите через `GET /b24-users?search=`
`userName`	string	нет	Имя пользователя (до 255 символов). Опционально, но рекомендуется для удобства чтения в UI
`departmentId`	string	да (для `type: "department"`)	ID отдела Битрикс24
`departmentName`	string	да (для `type: "department"`)	Имя отдела (до 255 символов)

Примеры

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

Terminal

# Добавить пользователя
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "userId": "243", "userName": "Катя Иванова"}'

# Добавить отдел
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "department", "departmentId": "5", "departmentName": "Разработка"}'

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

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "userId": "243", "userName": "Катя Иванова"}'

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

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'user',
      userId: '243',
      userName: 'Катя Иванова',
    }),
  }
)
if (res.status === 201) {
  const { data } = await res.json()
  console.log(`Добавлен: ${data.userName} (запись ${data.id})`)
}

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

javascript

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'department',
      departmentId: '5',
      departmentName: 'Разработка',
    }),
  }
)

Поля ответа

Поле	Тип	Описание
`success`	boolean	`true` при успешном добавлении. HTTP-статус — 201
`data.id`	string (UUID)	ID созданной записи — передавайте в `DELETE /access/:accessId` для удаления
`data.serverId`	string (UUID)	ID сервера
`data.userId`	string	ID пользователя Битрикс24 (только для `type: "user"`)
`data.userName`	string \| null	Имя пользователя (только для `type: "user"`)
`data.networkUserId`	string \| null	Network ID пользователя. `null` сразу после создания, заполняется асинхронно (только для `type: "user"`)
`data.departmentId`	string	ID отдела Битрикс24 (только для `type: "department"`)
`data.departmentName`	string	Имя отдела (только для `type: "department"`)
`data.grantedBy`	string (UUID)	ID пользователя Вайбкод, который создал запись
`data.createdAt`	string (ISO 8601)	Момент добавления

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

Добавление пользователя:

JSON

{
  "success": true,
  "data": {
    "id": "b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "userId": "243",
    "userName": "Катя Иванова",
    "networkUserId": null,
    "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
    "createdAt": "2026-04-22T10:15:00.000Z"
  }
}

Добавление отдела:

JSON

{
  "success": true,
  "data": {
    "id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "departmentId": "5",
    "departmentName": "Разработка",
    "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
    "createdAt": "2026-04-22T11:30:00.000Z"
  }
}

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

409 — запись уже существует:

JSON

{
  "success": false,
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Access entry already exists"
  }
}

Ошибки

HTTP	Код	Описание
400	`VALIDATION_ERROR`	Поля не прошли валидацию: неверный `type`, отсутствует обязательное поле для выбранного типа
400	`BLACKHOLE_ONLY`	Сервер в режиме OPEN
401	`MISSING_API_KEY`	Не передан заголовок `X-Api-Key`
401	`INVALID_API_KEY`	Неверный или просроченный API-ключ
404	`NOT_FOUND`	Сервер не существует, удалён или принадлежит другому API-ключу
409	`ALREADY_EXISTS`	Запись для этого `userId`/`departmentId` на этом сервере уже существует
429	`RATE_LIMITED`	Превышен общий лимит запросов платформы

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

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

userName и departmentName — только для отображения. Для сопоставления при проверке доступа используются userId/departmentId — имя на авторизацию не влияет. Имя используется для отображения в списке, когда интеграция с Битрикс24 временно недоступна.
networkUserId заполняется асинхронно. Сразу после POST поле null. В фоне платформа вызывает веб-хук Битрикс24 (если доступен), находит Network ID пользователя и обновляет запись. Это нужно для сопоставления, когда пользователь входит в Вайбкод через Network OAuth (а не через ваш портал).
Уникальность — пара (serverId, userId) для пользователей и (serverId, departmentId) для отделов. Чтобы «обновить» запись — сначала DELETE, потом POST.
Политика не меняется автоматически. Если сервер в OWNER_ONLY, добавление записи не сработает как «открытие доступа» — сначала переключите политику на NAMED_USERS (или DEPARTMENT) через `PATCH /access-policy`.

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

Список доступа — проверить, что запись добавилась.
Удалить запись — DELETE /v1/infra/servers/:id/access/:accessId.
Политика доступа — переключить NAMED_USERS / DEPARTMENT.
Поиск пользователей Битрикс24 — найти userId до добавления.

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

#Параметры

#Примеры

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

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

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

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

#Поля ответа

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

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

#Ошибки

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

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

#Добавить пользователя или отдел

#Параметры

#Поля запроса (body)

#Примеры

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

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

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

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

#Поля ответа

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

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

#Ошибки

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

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

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

Параметры

Примеры

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

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

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

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

Поля ответа

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

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

Ошибки

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

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

Добавить пользователя или отдел

Параметры

Поля запроса (body)

Примеры

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

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

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

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

Поля ответа

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

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

Ошибки

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

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