[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-infra\u002Faccess":3,"docs-tabs-infra\u002Faccess":6},{"content":4,"lastmod":5},"\n# Доступ и режимы\n\nУправление видимостью приложения и режимом сервера. Политика доступа (`accessPolicy`) определяет, кто из Битрикс24 может открыть HTTPS-субдомен приложения: только владелец, список конкретных пользователей и отделов, все пользователи портала или вообще любой посетитель. Режим сервера (`mode`) переключает между Black Hole (всё закрыто фаерволом) и OPEN (прямой доступ по IP).\n\n> **Смена `accessPolicy` с `OWNER_ONLY` на более открытую напрямую влияет на безопасность.** Никогда не делайте её от имени пользователя без явного подтверждения — это открывает приложение другим людям портала или всему интернету.\n\nСкоуп: `vibe:infra`\n\n## Операции\n\n- [SSH-данные](.\u002Faccess\u002Fssh.md) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fssh`\n- [Переключить режим](.\u002Faccess\u002Fmode.md) — `PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fmode`\n- [Политика доступа](.\u002Faccess\u002Faccess-policy.md) — `PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess-policy`\n- [Список доступа](.\u002Faccess\u002Faccess-list.md) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`\n- [Добавить пользователя\u002Fотдел](.\u002Faccess\u002Faccess-add.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`\n- [Удалить запись доступа](.\u002Faccess\u002Faccess-delete.md) — `DELETE \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess\u002F:accessId`\n- [Поиск пользователей Битрикс24](.\u002Faccess\u002Fb24-users.md) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fb24-users`\n\n## Политики доступа (от самой закрытой к самой открытой)\n\n| Политика | Кто видит HTTPS-субдомен |\n|----------|--------------------------|\n| `OWNER_ONLY` | Только владелец API-ключа (по умолчанию) |\n| `NAMED_USERS` | Пользователи из списка доступа |\n| `DEPARTMENT` | Отделы Битрикс24 из списка доступа |\n| `PORTAL` | Все пользователи портала Битрикс24 |\n| `AUTHENTICATED` | Все авторизованные пользователи (включая не-членов портала) |\n| `PUBLIC` | Все, без авторизации |\n\n## Типовой сценарий (NAMED_USERS)\n\nОткрыть приложение для конкретных сотрудников Битрикс24:\n\n1. Найти пользователей: [`GET \u002Fb24-users?search=Иван`](.\u002Faccess\u002Fb24-users.md).\n2. Переключить политику: [`PATCH \u002Faccess-policy`](.\u002Faccess\u002Faccess-policy.md) `{ accessPolicy: \"NAMED_USERS\" }`.\n3. Добавить пользователя: [`POST \u002Faccess`](.\u002Faccess\u002Faccess-add.md) `{ type: \"user\", userId: \"243\", userName: \"Катя Иванова\" }`.\n4. Проверить список: [`GET \u002Faccess`](.\u002Faccess\u002Faccess-list.md).\n5. Позже — удалить запись: [`DELETE \u002Faccess\u002F:accessId`](.\u002Faccess\u002Faccess-delete.md).\n\n## Сценарий «вернуть приватность»\n\n1. Перевести политику обратно в `OWNER_ONLY`: [`PATCH \u002Faccess-policy`](.\u002Faccess\u002Faccess-policy.md) `{ accessPolicy: \"OWNER_ONLY\" }`. Записи пользователей и отделов остаются в базе, но больше не применяются.\n2. При необходимости очистить историю — удалить все записи через [`DELETE \u002Faccess\u002F:accessId`](.\u002Faccess\u002Faccess-delete.md).\n\n## Смотрите также\n\n- [Жизненный цикл](\u002Fdocs\u002Finfra\u002Flifecycle) — start\u002Fstop\u002Fwake\u002Frepair.\n- [Корневой раздел — Инфраструктура](\u002Fdocs\u002Finfra) — обзор политик, статусов, ошибок.\n","2026-07-07",{"access\u002Fssh.md":7,"access\u002Fmode.md":8,"access\u002Faccess-policy.md":9,"access\u002Faccess-list.md":10,"access\u002Faccess-add.md":11,"access\u002Faccess-delete.md":12,"access\u002Fb24-users.md":13},"\n## SSH-данные\n\n`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fssh`\n\nВозвращает данные для SSH-подключения. Полноценный SSH-доступ (с паролем, приватным ключом и публичным ключом) возвращается только для серверов в режиме `OPEN`. Для `BLACKHOLE` все SSH-поля — `null`: сервер закрыт фаерволом iptables, и прямой SSH невозможен. Вместо SSH для BLACKHOLE используйте [Deploy API](\u002Fdocs\u002Finfra\u002Fdeploy) — `\u002Fexec`, `\u002Fupload`, `\u002Flogs`. Rate-limit: до 10 запросов в минуту на сервер.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fssh\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fssh\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fssh`,\n  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst { data } = await res.json()\n\nif (data.mode === 'OPEN') {\n  console.log('Команда:', data.sshCommand)\n  console.log('Пароль:', data.sshPassword)  \u002F\u002F если выдавался\n} else {\n  console.log(data.note)  \u002F\u002F BLACKHOLE — используйте Deploy API\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fssh`,\n  {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.mode` | string | `OPEN` или `BLACKHOLE` |\n| `data.ip` | string | Публичный IP сервера |\n| `data.sshDirect` | boolean | `true` для `OPEN` (SSH работает по IP), `false` для `BLACKHOLE` (закрыт файрволом) |\n| `data.sshUser` | string \\| null | Пользователь SSH: `ubuntu` или `root`. `null` для BLACKHOLE |\n| `data.sshPort` | number \\| null | Порт SSH: `22`. `null` для BLACKHOLE |\n| `data.sshPassword` | string \\| null | Пароль. Для BLACKHOLE всегда `null`. Для OPEN — пароль если сервер сгенерил один при переходе в OPEN |\n| `data.sshPrivateKey` | string \\| null | Приватный ключ OpenSSH (ed25519). Возвращается для OPEN-сервера, когда платформа его сгенерировала |\n| `data.sshPublicKey` | string \\| null | Публичный ключ (ed25519) — соответствующая публичная часть к `sshPrivateKey` |\n| `data.sshCommand` | string \\| null | Готовая команда для копирования: `ssh ubuntu@IP`. Для BLACKHOLE — `null` |\n| `data.appUrl` | string | HTTPS-адрес приложения (присутствует только для BLACKHOLE, где SSH недоступен) |\n| `data.note` | string | Пояснение для BLACKHOLE: «BLACKHOLE servers do not expose SSH. Use the Deploy API…» |\n\n## Пример ответа\n\nOPEN-сервер:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"mode\": \"OPEN\",\n    \"ip\": \"111.88.251.211\",\n    \"sshUser\": \"ubuntu\",\n    \"sshPort\": 22,\n    \"sshPassword\": \"Oi9owBO6zMbueGmM75J9hg\",\n    \"sshPrivateKey\": \"-----BEGIN OPENSSH PRIVATE KEY-----\\nb3BlbnNzaC1rZXktdjEAAAAABG5vbmU…\\n-----END OPENSSH PRIVATE KEY-----\\n\",\n    \"sshPublicKey\": \"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM0JAP1EMGh0CkT7RkZ26pTSa4X1FsWXe61cB5Fiqqjz vibe-generated\",\n    \"sshCommand\": \"ssh ubuntu@111.88.251.211\",\n    \"sshDirect\": true\n  }\n}\n```\n\nBLACKHOLE-сервер:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"mode\": \"BLACKHOLE\",\n    \"ip\": \"93.77.184.167\",\n    \"sshDirect\": false,\n    \"sshPassword\": null,\n    \"sshPrivateKey\": null,\n    \"sshPublicKey\": null,\n    \"sshCommand\": null,\n    \"appUrl\": \"https:\u002F\u002Fapp-abc12345.vibecode.bitrix24.tech\",\n    \"note\": \"BLACKHOLE servers do not expose SSH. Use the Deploy API (exec\u002Fupload\u002Flogs) instead.\"\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n404 — сервер не существует:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"NOT_FOUND\",\n    \"message\": \"Server not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен rate-limit (до 10 запросов в минуту на сервер) либо общий rate-limit платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Каждый BLACKHOLE → OPEN переход генерирует новый пароль.** Старые пароли (если они были) становятся недействительными. То же при обратном цикле BLACKHOLE → OPEN → BLACKHOLE → OPEN: на каждый вход в OPEN платформа генерирует свежий `sshPassword`. Пароль также возвращается в ответе на [`PATCH \u002Fmode`](.\u002Fmode.md) — можно сохранить оттуда.\n- **`sshPrivateKey` и `sshPublicKey` отдаются только для ключей, сгенерированных платформой.** Если при создании сервера через [`POST \u002Fv1\u002Finfra\u002Fservers`](\u002Fdocs\u002Finfra\u002Fservers\u002Fcreate) вы передали свой `sshPublicKey`, платформа не генерировала приватный ключ — поле `sshPrivateKey` в ответе будет `null`. Используйте свой приватный ключ со стороны клиента.\n- **`sshCommand` — готовая к копированию строка для AI-агентов и скриптов.** Это не отдельная команда запуска — просто `ssh ubuntu@IP`. Аутентификация через пароль или ключ — отдельный шаг на стороне SSH-клиента.\n- **Отдельное ограничение — 10 запросов в минуту на сервер** существует именно из-за чувствительности возвращаемых данных. Общий лимит платформы выше, но `\u002Fssh` ограничивается жёстче.\n\n## Смотрите также\n\n- [Переключить режим](.\u002Fmode.md) — `PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fmode` — перейти в OPEN\u002FBLACKHOLE.\n- [Выполнить команду](\u002Fdocs\u002Finfra\u002Fdeploy\u002Fexec) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fexec` — SSH-эквивалент для BLACKHOLE.\n- [Загрузить файл](\u002Fdocs\u002Finfra\u002Fdeploy\u002Fupload) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fupload` — scp-эквивалент для BLACKHOLE.\n- [Политика доступа](.\u002Faccess-policy.md) — кому видно приложение по HTTPS.\n","\n## Переключить режим\n\n`PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fmode`\n\nПереключает сервер между режимами `BLACKHOLE` (всё закрыто фаерволом, доступ только через HTTPS-субдомен) и `OPEN` (прямой доступ по IP, SSH на порту 22 открыт). При переходе в `OPEN` фаервол полностью снимается и генерируется SSH-пароль. При обратном переходе фаервол восстанавливается и пароль удаляется. Переход в `OPEN` запрещён, если платформа (флаг `openModeEnabled`) или портал (политика `allowOpenMode`) не разрешают его.\n\n> **OPEN отключает защиту Black Hole.** Сервер становится доступен из интернета по IP. Все Deploy API эндпоинты (`\u002Fexec`, `\u002Fupload`, `\u002Flogs`, `\u002Fdeploy`) работают только в BLACKHOLE-режиме — в OPEN они вернут ошибку.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|----------|\n| `mode` | string | **да** | Целевой режим: `OPEN` или `BLACKHOLE` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\n# BLACKHOLE → OPEN\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fmode \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"mode\": \"OPEN\"}'\n\n# OPEN → BLACKHOLE (вернуть защиту)\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fmode \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"mode\": \"BLACKHOLE\"}'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fmode \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"mode\": \"OPEN\"}'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fmode`,\n  {\n    method: 'PATCH',\n    headers: {\n      'X-Api-Key': 'YOUR_API_KEY',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ mode: 'OPEN' }),\n  }\n)\nconst { data } = await res.json()\nif (data.sshPassword) console.log(`Новый SSH-пароль: ${data.sshPassword}`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fmode`,\n  {\n    method: 'PATCH',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ mode: 'BLACKHOLE' }),\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.mode` | string | Новый режим (`OPEN` или `BLACKHOLE`) |\n| `data.ip` | string \\| null | IP сервера (не меняется при переключении) |\n| `data.sshPassword` | string \\| null | Сгенерированный SSH-пароль. Отдаётся только при переходе в `OPEN`. При переходе в `BLACKHOLE` — `null` |\n\n## Пример ответа\n\nПереход BLACKHOLE → OPEN:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"mode\": \"OPEN\",\n    \"ip\": \"178.154.230.106\",\n    \"sshPassword\": \"rT9xQ2mKaPzFHyB3\"\n  }\n}\n```\n\nПереход OPEN → BLACKHOLE:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"mode\": \"BLACKHOLE\",\n    \"ip\": \"178.154.230.106\",\n    \"sshPassword\": null\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — переход в `OPEN` запрещён политикой портала:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"OPEN_MODE_NOT_ALLOWED\",\n    \"message\": \"OPEN mode is not allowed by portal policy\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `INVALID_MODE` | `mode` не равен `OPEN` или `BLACKHOLE` |\n| 400 | `SAME_MODE` | Сервер уже в запрошенном режиме |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 403 | `OPEN_MODE_DISABLED` | Режим OPEN отключён на платформе (флаг `openModeEnabled`). Обратитесь к администратору платформы |\n| 403 | `OPEN_MODE_NOT_ALLOWED` | Режим OPEN запрещён политикой портала (флаг `allowOpenMode`). Обратитесь к администратору портала |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при смене конфигурации сети |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Порядок разрешения OPEN** (оба уровня должны пропустить): сначала платформенный флаг `openModeEnabled` — **платформенный админ тоже не обходит эту проверку**. Затем портальная политика `allowOpenMode` — **платформенный админ обходит её**. Только если оба разрешают, переход в OPEN возможен.\n- **IP не меняется при переключении.** Облачная виртуальная машина остаётся той же — меняются только правила iptables и SSH-конфигурация.\n- **Туннель (`blackholeStatus`) сохраняется в OPEN-режиме.** Агент Black Hole продолжает работать, HTTPS-субдомен остаётся рабочим — просто фаервол больше не блокирует внешний трафик. Однако Deploy API всё равно откажет: он требует именно BLACKHOLE.\n- **`accessPolicy` не применяется в OPEN.** В OPEN защита строится на SSH-ключах и iptables (который снят). Политика HTTPS-субдомена фактически не работает. При переключении значение `accessPolicy` сохраняется в базе — и снова начнёт действовать после возврата в BLACKHOLE.\n\n## Смотрите также\n\n- [SSH-данные](.\u002Fssh.md) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fssh` — получить пароль и команду после перехода в OPEN.\n- [Политика доступа](.\u002Faccess-policy.md) — `PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess-policy` — работает только в BLACKHOLE.\n- [Deploy API](\u002Fdocs\u002Finfra\u002Fdeploy) — доступен только в BLACKHOLE.\n- [Получить сервер](\u002Fdocs\u002Finfra\u002Fservers\u002Fget) — проверить текущий `mode`.\n","\n## Политика доступа\n\n`PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess-policy`\n\nОбновляет политику доступа для BLACKHOLE-сервера — определяет, кто из пользователей Битрикс24 может открывать приложение по HTTPS-субдомену (`app-{id}.vibecode.bitrix24.tech`). По умолчанию установлено `OWNER_ONLY` — только владелец API-ключа. Работает только в режиме `BLACKHOLE`. Для OPEN-сервера возвращается `BLACKHOLE_ONLY` — сначала переключите режим через [`PATCH \u002Fmode`](.\u002Fmode.md).\n\n> **Изменение `accessPolicy` с `OWNER_ONLY` на более открытую напрямую влияет на безопасность.** Смена на `PORTAL`, `AUTHENTICATED` или `PUBLIC` открывает приложение другим людям. **AI-агенты: никогда не вызывайте этот эндпоинт без явного подтверждения пользователя.**\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера в режиме BLACKHOLE |\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|----------|\n| `accessPolicy` | string | **да** | Одно из: `OWNER_ONLY`, `NAMED_USERS`, `DEPARTMENT`, `PORTAL`, `AUTHENTICATED`, `PUBLIC` |\n\nЗначения (от самой закрытой к самой открытой):\n\n| Значение | Кто видит приложение |\n|----------|---------------------|\n| `OWNER_ONLY` | Только владелец API-ключа (по умолчанию) |\n| `NAMED_USERS` | Конкретные пользователи из списка [`\u002Faccess`](.\u002Faccess-list.md) |\n| `DEPARTMENT` | Отделы Битрикс24 из списка [`\u002Faccess`](.\u002Faccess-list.md) |\n| `PORTAL` | Все пользователи портала Битрикс24 |\n| `AUTHENTICATED` | Все авторизованные пользователи (включая не-членов портала) |\n| `PUBLIC` | Все, без авторизации |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess-policy \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"accessPolicy\": \"PORTAL\"}'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess-policy \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"accessPolicy\": \"NAMED_USERS\"}'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess-policy`,\n  {\n    method: 'PATCH',\n    headers: {\n      'X-Api-Key': 'YOUR_API_KEY',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ accessPolicy: 'NAMED_USERS' }),\n  }\n)\nconst { data } = await res.json()\nconsole.log('Новая политика:', data.accessPolicy)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess-policy`,\n  {\n    method: 'PATCH',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ accessPolicy: 'OWNER_ONLY' }),\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.accessPolicy` | string | Новое значение политики (эхо) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accessPolicy\": \"PORTAL\"\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — сервер в режиме OPEN:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BLACKHOLE_ONLY\",\n    \"message\": \"Access policy is a Black Hole feature. Server is in OPEN mode — switch to BLACKHOLE via PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fmode first.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `VALIDATION_ERROR` | `accessPolicy` не в списке допустимых значений |\n| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN — политика не применима |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **`PUBLIC` особенно опасен.** Он делает приложение доступным без какой-либо авторизации — любому посетителю из интернета. Факт смены политики фиксируется в аудит-логе портала.\n- **`NAMED_USERS` и `DEPARTMENT` требуют непустых списков доступа.** Сама смена политики не добавляет пользователей — список ведётся отдельно через [`POST \u002Faccess`](.\u002Faccess-add.md). Если список пустой при `NAMED_USERS`\u002F`DEPARTMENT`, приложение будет недоступно никому, кроме владельца (автоматического отката к `OWNER_ONLY` не происходит).\n- **При возврате в `OWNER_ONLY` записи в `\u002Faccess` сохраняются в базе.** Они не применяются, пока политика не `NAMED_USERS`\u002F`DEPARTMENT`. Если захотите очистить историю — удалите записи через [`DELETE \u002Faccess\u002F:accessId`](.\u002Faccess-delete.md).\n- **При смене режима на OPEN `accessPolicy` не меняется**, но и не применяется: в OPEN защита идёт через SSH-ключи и iptables. При возврате в BLACKHOLE политика снова станет действующей.\n- **`AUTHENTICATED` включает не-членов портала.** В отличие от `PORTAL`, `AUTHENTICATED` пропускает любого авторизованного пользователя Битрикс24 (в том числе тех, кто не состоит в вашем портале). Подходит для приложений-гостевых форм, но снимает привязку к своему портальному коллективу.\n- **Владелец API-ключа всегда имеет доступ** — он не удаляется из списка при смене политики. Чтобы забрать доступ у себя, нужен запрос с другого ключа.\n\n## Смотрите также\n\n- [Список доступа](.\u002Faccess-list.md) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess` — кого сейчас видит политика.\n- [Добавить пользователя\u002Fотдел](.\u002Faccess-add.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`.\n- [Удалить запись доступа](.\u002Faccess-delete.md) — `DELETE \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess\u002F:accessId`.\n- [Поиск пользователей Битрикс24](.\u002Fb24-users.md) — найти `userId` для `NAMED_USERS`.\n- [Переключить режим](.\u002Fmode.md) — политика работает только в BLACKHOLE.\n","\n## Список доступа\n\n`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`\n\nВозвращает список пользователей и отделов Битрикс24 с доступом к приложению. Применяется, когда [`accessPolicy`](.\u002Faccess-policy.md) установлено в `NAMED_USERS` (список пользователей) или `DEPARTMENT` (список отделов). Работает только для BLACKHOLE-серверов. При `OWNER_ONLY`, `PORTAL`, `AUTHENTICATED`, `PUBLIC` списки в базе сохраняются, но не применяются.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess`,\n  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst { data } = await res.json()\n\nconsole.log(`Пользователей: ${data.users.length}`)\nconsole.log(`Отделов: ${data.departments.length}`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess`,\n  {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.users` | array | Записи доступа пользователей, отсортированные по `createdAt` (новые сверху) |\n| `data.users[].id` | string (UUID) | ID записи в таблице — нужен для [`DELETE`](.\u002Faccess-delete.md) |\n| `data.users[].userId` | string | ID пользователя Битрикс24 |\n| `data.users[].userName` | string \\| null | Имя пользователя (необязательное, заполняется при добавлении) |\n| `data.users[].networkUserId` | string \\| null | Network ID пользователя — заполняется асинхронно после добавления, используется для сопоставления при входе через Вайбкод-сессию |\n| `data.users[].grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |\n| `data.users[].createdAt` | string (ISO 8601) | Момент добавления |\n| `data.departments` | array | Записи доступа отделов |\n| `data.departments[].id` | string (UUID) | ID записи — нужен для [`DELETE`](.\u002Faccess-delete.md) |\n| `data.departments[].departmentId` | string | ID отдела Битрикс24 |\n| `data.departments[].departmentName` | string | Имя отдела (обязательное при добавлении) |\n| `data.departments[].grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |\n| `data.departments[].createdAt` | string (ISO 8601) | Момент добавления |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"users\": [\n      {\n        \"id\": \"b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60\",\n        \"serverId\": \"e765edfc-ba0a-43de-b8ea-838dd872c522\",\n        \"userId\": \"243\",\n        \"userName\": \"Катя Иванова\",\n        \"networkUserId\": \"net_90126\",\n        \"grantedBy\": \"f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70\",\n        \"createdAt\": \"2026-04-20T10:15:00.000Z\"\n      }\n    ],\n    \"departments\": [\n      {\n        \"id\": \"c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f\",\n        \"serverId\": \"e765edfc-ba0a-43de-b8ea-838dd872c522\",\n        \"departmentId\": \"5\",\n        \"departmentName\": \"Разработка\",\n        \"grantedBy\": \"f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70\",\n        \"createdAt\": \"2026-04-20T11:30:00.000Z\"\n      }\n    ]\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — сервер в режиме OPEN:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BLACKHOLE_ONLY\",\n    \"message\": \"Access lists are a Black Hole feature. Server is in OPEN mode — switch to BLACKHOLE via PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fmode first.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Обе коллекции отдаются независимо от текущей политики.** Можно вести список пользователей и список отделов параллельно, а переключать активную политику через [`PATCH \u002Faccess-policy`](.\u002Faccess-policy.md) позже.\n- **`networkUserId` заполняется асинхронно.** Первые секунды после [`POST \u002Faccess`](.\u002Faccess-add.md) поле может быть `null` — затем фоновый запрос к Битрикс24 проставит Network ID (он нужен для Вайбкод-сессий, если пользователь входит в Вайбкод через Вайбкод-логин, а не через OAuth Битрикс24).\n- **`grantedBy` — ID пользователя Вайбкод, не Битрикс24.** Соответствует `User.id` в базе платформы, не `userId` на портале Битрикс24. Если запись создана из UI — это автор вызова. Если через API-ключ — владелец ключа.\n- **Список не пагинируется и не имеет принудительного лимита.** Эндпоинт возвращает все записи `BlackHoleAccess` и `BlackHoleDepartment` для сервера. На практике количество — десятки записей: список пополняется вручную через [`POST \u002Faccess`](.\u002Faccess-add.md).\n\n## Смотрите также\n\n- [Добавить пользователя\u002Fотдел](.\u002Faccess-add.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`.\n- [Удалить запись](.\u002Faccess-delete.md) — `DELETE \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess\u002F:accessId` (здесь и используется `id` из ответа).\n- [Политика доступа](.\u002Faccess-policy.md) — переключить `NAMED_USERS` \u002F `DEPARTMENT`.\n- [Поиск пользователей Битрикс24](.\u002Fb24-users.md) — найти `userId`.\n","\n## Добавить пользователя или отдел\n\n`POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`\n\nДобавляет запись доступа к BLACKHOLE-серверу: конкретного пользователя Битрикс24 (при политике `NAMED_USERS`) или отдел (при политике `DEPARTMENT`). Политика при этом не меняется автоматически — смените её через [`PATCH \u002Faccess-policy`](.\u002Faccess-policy.md) отдельно, если ещё не переключали. Дубликаты (тот же `userId` или `departmentId` на том же сервере) возвращают 409 `ALREADY_EXISTS`.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера |\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|----------|\n| `type` | string | **да** | `user` — добавить пользователя, `department` — добавить отдел |\n| `userId` | string | да (для `type: \"user\"`) | ID пользователя Битрикс24. Ищите через [`GET \u002Fb24-users?search=`](.\u002Fb24-users.md) |\n| `userName` | string | нет | Имя пользователя (до 255 символов). Опционально, но рекомендуется для удобства чтения в UI |\n| `departmentId` | string | да (для `type: \"department\"`) | ID отдела Битрикс24 |\n| `departmentName` | string | да (для `type: \"department\"`) | Имя отдела (до 255 символов) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\n# Добавить пользователя\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"type\": \"user\", \"userId\": \"243\", \"userName\": \"Катя Иванова\"}'\n\n# Добавить отдел\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"type\": \"department\", \"departmentId\": \"5\", \"departmentName\": \"Разработка\"}'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"type\": \"user\", \"userId\": \"243\", \"userName\": \"Катя Иванова\"}'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess`,\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_API_KEY',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({\n      type: 'user',\n      userId: '243',\n      userName: 'Катя Иванова',\n    }),\n  }\n)\nif (res.status === 201) {\n  const { data } = await res.json()\n  console.log(`Добавлен: ${data.userName} (запись ${data.id})`)\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess`,\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({\n      type: 'department',\n      departmentId: '5',\n      departmentName: 'Разработка',\n    }),\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | `true` при успешном добавлении. HTTP-статус — 201 |\n| `data.id` | string (UUID) | ID созданной записи — передавайте в [`DELETE \u002Faccess\u002F:accessId`](.\u002Faccess-delete.md) для удаления |\n| `data.serverId` | string (UUID) | ID сервера |\n| `data.userId` | string | ID пользователя Битрикс24 (только для `type: \"user\"`) |\n| `data.userName` | string \\| null | Имя пользователя (только для `type: \"user\"`) |\n| `data.networkUserId` | string \\| null | Network ID пользователя. `null` сразу после создания, заполняется асинхронно (только для `type: \"user\"`) |\n| `data.departmentId` | string | ID отдела Битрикс24 (только для `type: \"department\"`) |\n| `data.departmentName` | string | Имя отдела (только для `type: \"department\"`) |\n| `data.grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |\n| `data.createdAt` | string (ISO 8601) | Момент добавления |\n\n## Пример ответа\n\nДобавление пользователя:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60\",\n    \"serverId\": \"e765edfc-ba0a-43de-b8ea-838dd872c522\",\n    \"userId\": \"243\",\n    \"userName\": \"Катя Иванова\",\n    \"networkUserId\": null,\n    \"grantedBy\": \"f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70\",\n    \"createdAt\": \"2026-04-22T10:15:00.000Z\"\n  }\n}\n```\n\nДобавление отдела:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f\",\n    \"serverId\": \"e765edfc-ba0a-43de-b8ea-838dd872c522\",\n    \"departmentId\": \"5\",\n    \"departmentName\": \"Разработка\",\n    \"grantedBy\": \"f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70\",\n    \"createdAt\": \"2026-04-22T11:30:00.000Z\"\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n409 — запись уже существует:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ALREADY_EXISTS\",\n    \"message\": \"Access entry already exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `VALIDATION_ERROR` | Поля не прошли валидацию: неверный `type`, отсутствует обязательное поле для выбранного типа |\n| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 409 | `ALREADY_EXISTS` | Запись для этого `userId`\u002F`departmentId` на этом сервере уже существует |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **`userName` и `departmentName` — только для отображения.** Для сопоставления при проверке доступа используются `userId`\u002F`departmentId` — имя на авторизацию не влияет. Имя используется для отображения в списке, когда интеграция с Битрикс24 временно недоступна.\n- **`networkUserId` заполняется асинхронно.** Сразу после `POST` поле `null`. В фоне платформа вызывает веб-хук Битрикс24 (если доступен), находит Network ID пользователя и обновляет запись. Это нужно для сопоставления, когда пользователь входит в Вайбкод через Network OAuth (а не через ваш портал).\n- **Уникальность — пара `(serverId, userId)` для пользователей и `(serverId, departmentId)` для отделов.** Чтобы «обновить» запись — сначала `DELETE`, потом `POST`.\n- **Политика не меняется автоматически.** Если сервер в `OWNER_ONLY`, добавление записи не сработает как «открытие доступа» — сначала переключите политику на `NAMED_USERS` (или `DEPARTMENT`) через [`PATCH \u002Faccess-policy`](.\u002Faccess-policy.md).\n\n## Смотрите также\n\n- [Список доступа](.\u002Faccess-list.md) — проверить, что запись добавилась.\n- [Удалить запись](.\u002Faccess-delete.md) — `DELETE \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess\u002F:accessId`.\n- [Политика доступа](.\u002Faccess-policy.md) — переключить `NAMED_USERS` \u002F `DEPARTMENT`.\n- [Поиск пользователей Битрикс24](.\u002Fb24-users.md) — найти `userId` до добавления.\n","\n## Удалить запись доступа\n\n`DELETE \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess\u002F:accessId`\n\nУдаляет запись доступа — пользователя или отдел — из списка BLACKHOLE-сервера. Эндпоинт универсальный: один и тот же `accessId` может относиться либо к пользователю (`BlackHoleAccess`), либо к отделу (`BlackHoleDepartment`) — платформа сначала ищет в первой таблице, потом во второй. После удаления запись исчезает из [`GET \u002Faccess`](.\u002Faccess-list.md).\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера |\n| `accessId` | path | string (UUID) | да | ID записи доступа из [`GET \u002Faccess`](.\u002Faccess-list.md) или [`POST \u002Faccess`](.\u002Faccess-add.md) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X DELETE -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess\u002Fb3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X DELETE -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Faccess\u002FACCESS_ID\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess\u002F${accessId}`,\n  {\n    method: 'DELETE',\n    headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n  }\n)\nconst { success } = await res.json()\nif (success) console.log('Запись удалена')\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Faccess\u002F${accessId}`,\n  {\n    method: 'DELETE',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | `true` при успешном удалении |\n\n## Пример ответа\n\n```json\n{ \"success\": true }\n```\n\n## Пример ответа при ошибке\n\n404 — запись не найдена (уже удалена, неверный accessId, либо accessId другого сервера):\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"NOT_FOUND\",\n    \"message\": \"Access entry not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует или запись не найдена (неверный `accessId`, уже удалена, или принадлежит другому серверу) |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Физическое удаление, не пометка на удаление.** Запись стирается из базы. Восстановить нельзя — придётся повторно вызывать [`POST \u002Faccess`](.\u002Faccess-add.md).\n- **`accessId` привязан к серверу.** Попытка удалить запись доступа другого сервера (правильный `accessId`, но неверный `:id` в пути) вернёт 404 `NOT_FOUND`. Платформа намеренно не раскрывает факт существования записей чужих серверов.\n- **Удаление не меняет политику.** Если вы удалите всех пользователей при `accessPolicy: \"NAMED_USERS\"`, политика останется `NAMED_USERS` (и приложение станет недоступно никому, кроме владельца ключа). Чтобы «полностью вернуть приватность» — меняйте политику обратно на `OWNER_ONLY` через [`PATCH \u002Faccess-policy`](.\u002Faccess-policy.md).\n- **Владельца ключа удалить нельзя.** Владелец всегда имеет доступ, даже если его нет в списке. Чтобы забрать у себя доступ — нужен другой API-ключ.\n\n## Смотрите также\n\n- [Список доступа](.\u002Faccess-list.md) — получить `accessId` для удаления.\n- [Добавить пользователя\u002Fотдел](.\u002Faccess-add.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess`.\n- [Политика доступа](.\u002Faccess-policy.md) — `PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess-policy`.\n","\n## Поиск пользователей Битрикс24\n\n`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fb24-users`\n\nИщет пользователей на портале Битрикс24 по имени, фамилии или email — возвращает `userId`, имя, должность и фото для каждого совпадения. Используется для заполнения списка `NAMED_USERS` через [`POST \u002Faccess`](.\u002Faccess-add.md), когда известно имя человека, но не его ID на портале. Работает через веб-хук-ключ из [apiKey.webhookUrl](\u002Fdocs\u002Fkeys-auth). Если у текущего API-ключа `webhookUrl` отсутствует (например, OAuth-ключ без связанного вебхука), эндпоинт вернёт пустой массив.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n| `search` | query | string | **да** | Строка поиска, минимум 2 символа. Ищет по имени, фамилии и email |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fb24-users?search=Иван\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fb24-users?search=Иван\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst q = encodeURIComponent('Иван')\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fb24-users?search=${q}`,\n  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst { data: users } = await res.json()\nusers.forEach(u => console.log(`${u.id}: ${u.name} — ${u.position ?? 'без должности'}`))\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fb24-users?search=${q}`,\n  {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив найденных пользователей |\n| `data[].id` | string | ID пользователя Битрикс24 — передавайте в `userId` при [`POST \u002Faccess`](.\u002Faccess-add.md) |\n| `data[].name` | string | Полное имя (имя + фамилия) |\n| `data[].photo` | string \\| null | URL аватарки (может быть `null`) |\n| `data[].position` | string \\| null | Должность (может быть `null`) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"243\",\n      \"name\": \"Катя Иванова\",\n      \"photo\": null,\n      \"position\": null\n    }\n  ]\n}\n```\n\n## Пример ответа при ошибке\n\n400 — строка поиска короче 2 символов:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"search query required (min 2 chars)\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `VALIDATION_ERROR` | `search` отсутствует или короче 2 символов |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Почему пустой массив при отсутствии `webhookUrl`.** Это сделано специально — клиент может работать одинаково с любым типом ключа: при отсутствии вебхука получает пустой результат (без ошибки) и переключается на альтернативный инструмент поиска.\n- **Поиск выполняется через метод `user.search` на портале Битрикс24.** То есть логика совпадения с UI портала — те же правила по имени\u002Fфамилии\u002Femail.\n- **Кириллица в URL — через `encodeURIComponent`.** На JS: `encodeURIComponent('Иван')`. На curl: `?search=%D0%98%D0%B2%D0%B0%D0%BD`.\n- **Не зависит от режима сервера.** Поиск работает для любого сервера — и BLACKHOLE, и OPEN. Логически он нужен для `NAMED_USERS`, но эндпоинт не ограничивает вызов по `mode`.\n\n## Смотрите также\n\n- [Добавить пользователя\u002Fотдел](.\u002Faccess-add.md) — добавить найденного пользователя в список доступа.\n- [Список доступа](.\u002Faccess-list.md) — увидеть уже добавленных пользователей и отделов.\n- [Политика доступа](.\u002Faccess-policy.md) — переключиться на `NAMED_USERS`.\n"]