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

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

Переключает сервер между режимами BLACKHOLE (всё закрыто фаерволом, доступ только через HTTPS-субдомен) и OPEN (прямой доступ по IP, SSH на порту 22 открыт). При переходе в OPEN фаервол полностью снимается и генерируется SSH-пароль. При обратном переходе фаервол восстанавливается и пароль удаляется. Переход в OPEN запрещён, если платформа (флаг openModeEnabled) или портал (политика allowOpenMode) не разрешают его.

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

#Параметры

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

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

Поле Тип Обяз. Описание
mode string да Целевой режим: OPEN или BLACKHOLE

#Примеры

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

Terminal 
# BLACKHOLE → OPEN
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": "OPEN"}'

# OPEN → BLACKHOLE (вернуть защиту)
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-приложение

Terminal 
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": "OPEN"}'

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

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: 'OPEN' }),
  }
)
const { data } = await res.json()
if (data.sshPassword) console.log(`Новый SSH-пароль: ${data.sshPassword}`)

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

javascript 
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' }),
  }
)

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.mode string Новый режим (OPEN или BLACKHOLE)
data.ip string | null IP сервера (не меняется при переключении)
data.sshPassword string | null Сгенерированный SSH-пароль. Отдаётся только при переходе в OPEN. При переходе в BLACKHOLE — null

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

Переход BLACKHOLE → OPEN:

JSON 
{
  "success": true,
  "data": {
    "mode": "OPEN",
    "ip": "178.154.230.106",
    "sshPassword": "rT9xQ2mKaPzFHyB3"
  }
}

Переход OPEN → BLACKHOLE:

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

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

403 — переход в OPEN запрещён политикой портала:

JSON 
{
  "success": false,
  "error": {
    "code": "OPEN_MODE_NOT_ALLOWED",
    "message": "OPEN mode is not allowed by portal policy"
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_MODE mode не равен OPEN или BLACKHOLE
400 SAME_MODE Сервер уже в запрошенном режиме
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
403 OPEN_MODE_DISABLED Режим OPEN отключён на платформе (флаг openModeEnabled). Обратитесь к администратору платформы
403 OPEN_MODE_NOT_ALLOWED Режим OPEN запрещён политикой портала (флаг allowOpenMode). Обратитесь к администратору портала
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы
502 PROVIDER_ERROR Облачный провайдер вернул ошибку при смене конфигурации сети

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

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

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

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