#Политика доступа

PATCH /v1/infra/servers/:id/access-policy

Обновляет политику доступа для BLACKHOLE-сервера — определяет, кто из пользователей Битрикс24 может открывать приложение по HTTPS-субдомену (app-{id}.vibecode.bitrix24.tech). По умолчанию установлено OWNER_ONLY — только владелец API-ключа. Работает только в режиме BLACKHOLE; для OPEN-сервера возвращается BLACKHOLE_ONLY — сначала переключите режим через `PATCH /mode`.

Изменение accessPolicy с OWNER_ONLY на более открытую напрямую влияет на безопасность. Смена на PORTAL, AUTHENTICATED или PUBLIC открывает приложение другим людям. AI-агенты: никогда не вызывайте этот эндпоинт без явного подтверждения пользователя.

#Параметры

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

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

Поле Тип Обяз. Описание
accessPolicy string да Одно из: OWNER_ONLY, NAMED_USERS, DEPARTMENT, PORTAL, AUTHENTICATED, PUBLIC

Значения (от самой закрытой к самой открытой):

Значение Кто видит приложение
OWNER_ONLY Только владелец API-ключа (по умолчанию)
NAMED_USERS Конкретные пользователи из списка `/access`
DEPARTMENT Отделы Битрикс24 из списка `/access`
PORTAL Все пользователи портала Битрикс24
AUTHENTICATED Все авторизованные пользователи (включая не-членов портала)
PUBLIC Все, без авторизации

#Примеры

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "PORTAL"}'

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "NAMED_USERS"}'

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

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'NAMED_USERS' }),
  }
)
const { data } = await res.json()
console.log('Новая политика:', data.accessPolicy)

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

javascript 
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'OWNER_ONLY' }),
  }
)

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.accessPolicy string Новое значение политики (эхо)

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

JSON 
{
  "success": true,
  "data": {
    "accessPolicy": "PORTAL"
  }
}

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

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

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

#Ошибки

HTTP Код Описание
400 VALIDATION_ERROR accessPolicy не в списке допустимых значений
400 BLACKHOLE_ONLY Сервер в режиме OPEN — политика не применима
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

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

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

  • PUBLIC особенно опасен. Он делает приложение доступным без какой-либо авторизации — любому посетителю из интернета. Факт смены политики фиксируется в аудит-логе портала.
  • NAMED_USERS и DEPARTMENT требуют непустых списков доступа. Сама смена политики не добавляет пользователей — список ведётся отдельно через `POST /access`. Если список пустой при NAMED_USERS/DEPARTMENT, приложение будет недоступно никому, кроме владельца (fallback к OWNER_ONLY не происходит).
  • При возврате в OWNER_ONLY записи в /access сохраняются в базе. Они не применяются, пока политика не NAMED_USERS/DEPARTMENT. Если захотите очистить историю — удалите записи через `DELETE /access/:accessId`.
  • При смене режима на OPEN accessPolicy не меняется, но и не применяется: в OPEN защита идёт через SSH-ключи и iptables. При возврате в BLACKHOLE политика снова станет действующей.
  • AUTHENTICATED включает не-членов портала. В отличие от PORTAL, AUTHENTICATED пропускает любого авторизованного пользователя Битрикс24 (в том числе тех, кто не состоит в вашем портале). Подходит для приложений-гостевых форм, но снимает привязку к своему портальному коллективу.
  • Владелец API-ключа всегда имеет доступ — он не удаляется из списка при смене политики. Чтобы забрать доступ у себя, нужен запрос с другого ключа.

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