Переключить режим

PATCH /v1/infra/servers/:id/mode

Возвращает сервер из открытого режима OPEN в защищённый режим BLACKHOLE: фаервол восстанавливается, SSH-пароль удаляется. Перевести сервер в OPEN через API нельзя, это делает человек в кабинете.

Запрос с mode: "OPEN" отклоняется до любых действий с сервером и его сетью. Пока режим OPEN выключен на уровне платформы, приходит 403 OPEN_MODE_DISABLED, и перевести сервер в OPEN в это время не может никто, в том числе из кабинета. Когда режим на платформе включён, приходит 403 DIRECT_NETWORK_CHANGE_REQUIRES_HUMAN со ссылкой на карточку сервера в кабинете.

OPEN отключает защиту Black Hole. Сервер становится доступен из интернета по IP. Все Deploy API эндпоинты (/exec, /upload, /logs, /deploy) работают только в BLACKHOLE-режиме — в OPEN они вернут ошибку.

Параметры

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

Примеры

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

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

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

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

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/mode`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ mode: 'BLACKHOLE' }),
  }
)
const { data } = await res.json()
console.log(`Режим сервера: ${data.mode}`)

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

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

Поля ответа

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

Переход OPEN → BLACKHOLE:

{
  "success": true,
  "data": {
    "mode": "BLACKHOLE",
    "ip": "178.154.230.106",
    "sshPassword": null
  }
}

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

403 — запрос на переход в OPEN, когда режим на платформе включён:

{
  "success": false,
  "error": {
    "code": "DIRECT_NETWORK_CHANGE_REQUIRES_HUMAN",
    "message": "Opening direct network access requires a current human cabinet session",
    "details": {
      "settingsUrl": "https://vibecode.bitrix24.tech/servers/3f2b9c1e-7a4d-4e8b-9c5f-1d2e3a4b5c6d"
    }
  }
}

Ошибки

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

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

• В кабинете перевод в OPEN проходит три проверки. Режим включён на уровне платформы, портал работает на коммерческом тарифе Битрикс24 и разрешает OPEN политикой allowOpenMode.
• Ссылка «Переключить в OPEN» видна не всегда. Она стоит в блоке SSH вкладки «Деплой», пока сервер в статусе running и агент Black Hole в статусе CONNECTED. Пока режим OPEN выключен на уровне платформы, ссылки нет — блок показывает пояснение вместо неё.
• IP не меняется при переключении. Облачная виртуальная машина остаётся той же — меняются сетевая политика и SSH-конфигурация.
• Сетевую политику держат два слоя. Внутренний — правила iptables на самой машине, внешний стоит снаружи неё и не снимается изнутри. Переключение режима меняет оба, внешний слой первым. Там, где внешний слой для сервера не поддержан, работает только внутренний, и поведение ручки прежнее.
• Обрыв связи посреди переключения закрывает фаервол обратно. Если связь с сервером потерялась после смены внешнего слоя, платформа закрывает фаервол машины и возвращает внешний слой на прежнюю роль, и только потом отдаёт ошибку. Закрытие идёт по тому же каналу связи, который оборвался, поэтому на полностью недоступном сервере оно тоже не доедет.
• Сбой записи режима после закрытия сервера фаервол обратно не открывает. Машина остаётся закрытой на обоих слоях, а строка сервера продолжает показывать OPEN.
• Туннель (blackholeStatus) сохраняется в OPEN-режиме. Агент Black Hole продолжает работать, HTTPS-субдомен остаётся рабочим, а фаервол больше не блокирует внешний трафик. Однако Deploy API всё равно откажет: он требует именно BLACKHOLE.
• accessPolicy не применяется в OPEN. В OPEN защита строится на SSH-ключах и iptables (который снят). Политика HTTPS-субдомена фактически не работает. При переключении значение accessPolicy сохраняется в базе — и снова начнёт действовать после возврата в BLACKHOLE.

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

• SSH-данные
• Политика доступа
• Deploy API
• Получить сервер