Для 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 — личный ключ
curl -H "X-Api-Key: YOUR_API_KEY" \
https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access
curl — OAuth-приложение
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 — личный ключ
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-приложение
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) | ОписаниеМомент добавления |
Пример ответа
{
"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:
{
"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 | Код | Описание |
|---|---|---|
| HTTP400 | КодBLACKHOLE_ONLY |
ОписаниеСервер в режиме OPEN |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP403 | КодSERVER_ROLE_FORBIDDEN |
ОписаниеВы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В error.hint придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — Список серверов |
| HTTP404 | КодNOT_FOUND |
ОписаниеСервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| HTTP429 | Код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.