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

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 — Ошибки.

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

• Подтверждённый запрос ещё нужно применить. На защищённых порталах расширение доступа может требовать подтверждения человеком. В error.details приходят proposalId, approvalUrl, expiresAt и retryOperation. Передайте approvalUrl человеку с правом согласовать доступ. Проверьте запрос и после APPROVED повторите исходный PATCH, добавив approvalId. Сохраните тот же ключ и accessPolicy. Объект retryOperation описывает согласованную операцию и не является телом HTTP-запроса.

• PUBLIC особенно опасен. Он делает приложение доступным без какой-либо авторизации — любому посетителю из интернета. Факт смены политики фиксируется в аудит-логе портала.

• NAMED_USERS и DEPARTMENT требуют непустых списков доступа. Сама смена политики не добавляет пользователей — список ведётся отдельно через POST /access. Если список пустой при NAMED_USERS/DEPARTMENT, приложение будет недоступно никому, кроме владельца (автоматического отката к OWNER_ONLY не происходит).

• Новая политика действует и на уже открытые сессии. Если она больше не пускает пользователя, приложение перестаёт у него открываться в течение минуты. Исключение — переход на OWNER_ONLY: часть открытых сессий работает до конца своего срока, до 40 минут, но продлиться уже не может. Если переводите сервер в OWNER_ONLY, чтобы сразу закрыть доступ, учитывайте этот срок.

• Доступ по ссылкам share-url смена политики не закрывает. Их отзывают отдельно — Отозвать токен.

• При возврате в OWNER_ONLY записи в /access сохраняются в базе. Они не применяются, пока политика не NAMED_USERS/DEPARTMENT. Если захотите очистить историю — удалите записи через DELETE /access/:accessId.

• При смене режима на OPEN accessPolicy не меняется, но и не применяется: в OPEN защита идёт через SSH-ключи и iptables. При возврате в BLACKHOLE политика снова станет действующей.

• AUTHENTICATED включает не-членов портала. В отличие от PORTAL, AUTHENTICATED пропускает любого авторизованного пользователя Битрикс24 (в том числе тех, кто не состоит в вашем портале). Подходит для приложений-гостевых форм, но снимает привязку к своему портальному коллективу.

• Владелец API-ключа всегда имеет доступ — он не удаляется из списка при смене политики. Чтобы забрать доступ у себя, нужен запрос с другого ключа.

• При открытии из каталога Битрикс24 членство в портале подтверждает сам портал. Сотруднику не нужна учётная запись Вайбкод: приложение с политикой PORTAL (а также AUTHENTICATED и PUBLIC) открывается всем сотрудникам, как и обещано. Платформа дополнительно спрашивает у Битрикс24, что это активный сотрудник, а не уволенный и не внешний гость. Именные политики (OWNER_ONLY, NAMED_USERS, DEPARTMENT) этим путём не открываются — они решают по конкретному человеку, поэтому сотруднику нужно один раз войти в Вайбкод.

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

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