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

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-агенты: никогда не вызывайте этот эндпоинт без явного подтверждения пользователя.

Параметры

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

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

Примеры

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

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-приложение

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 — личный ключ

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-приложение

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": true,
  "data": {
    "accessPolicy": "PORTAL"
  }
}

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

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

{
  "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."
  }
}

Ошибки

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

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

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

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

• Список доступа
• Добавить пользователя/отдел
• Удалить запись доступа
• Поиск пользователей Битрикс24
• Переключить режим