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

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 они вернут ошибку.

#Параметры

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

#Примеры

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

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

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

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

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

#Поля ответа

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

Переход BLACKHOLE → OPEN:

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

Переход OPEN → BLACKHOLE:

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

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

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

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

#Ошибки

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

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

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

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

• SSH-данные — GET /v1/infra/servers/:id/ssh — получить пароль и команду после перехода в OPEN.
• Политика доступа — PATCH /v1/infra/servers/:id/access-policy — работает только в BLACKHOLE.
• Deploy API — доступен только в BLACKHOLE.
• Получить сервер — проверить текущий mode.

#SSH-данные

GET /v1/infra/servers/:id/ssh

Возвращает данные для SSH-подключения. Полноценный SSH-доступ (с паролем, приватным ключом и публичным ключом) возвращается только для серверов в режиме OPEN. Для BLACKHOLE все SSH-поля — null: сервер закрыт фаерволом iptables, и прямой SSH невозможен. Вместо SSH для BLACKHOLE используйте Deploy API — /exec, /upload, /logs. Rate-limit: до 10 запросов в минуту на сервер.

#Параметры

#Примеры

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

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/ssh

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

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/ssh

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/ssh`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data } = await res.json()

if (data.mode === 'OPEN') {
  console.log('Команда:', data.sshCommand)
  console.log('Пароль:', data.sshPassword)  // если выдавался
} else {
  console.log(data.note)  // BLACKHOLE — используйте Deploy API
}

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/ssh`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

#Поля ответа

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

OPEN-сервер:

{
  "success": true,
  "data": {
    "mode": "OPEN",
    "ip": "111.88.251.211",
    "sshUser": "ubuntu",
    "sshPort": 22,
    "sshPassword": "Oi9owBO6zMbueGmM75J9hg",
    "sshPrivateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAABG5vbmU…\n-----END OPENSSH PRIVATE KEY-----\n",
    "sshPublicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM0JAP1EMGh0CkT7RkZ26pTSa4X1FsWXe61cB5Fiqqjz vibe-generated",
    "sshCommand": "ssh ubuntu@111.88.251.211",
    "sshDirect": true
  }
}

BLACKHOLE-сервер:

{
  "success": true,
  "data": {
    "mode": "BLACKHOLE",
    "ip": "93.77.184.167",
    "sshDirect": false,
    "sshPassword": null,
    "sshPrivateKey": null,
    "sshPublicKey": null,
    "sshCommand": null,
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech",
    "note": "BLACKHOLE servers do not expose SSH. Use the Deploy API (exec/upload/logs) instead."
  }
}

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

404 — сервер не существует:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}

#Ошибки

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

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

• Каждый BLACKHOLE → OPEN переход генерирует новый пароль. Старые пароли (если они были) становятся недействительными. То же при обратном цикле BLACKHOLE → OPEN → BLACKHOLE → OPEN: на каждый вход в OPEN платформа генерирует свежий sshPassword. Пароль также возвращается в ответе на `PATCH /mode` — можно сохранить оттуда.
• sshPrivateKey и sshPublicKey отдаются только для ключей, сгенерированных платформой. Если при создании сервера через `POST /v1/infra/servers` вы передали свой sshPublicKey, платформа не генерировала приватный ключ — поле sshPrivateKey в ответе будет null. Используйте свой приватный ключ со стороны клиента.
• sshCommand — готовая к копированию строка для AI-агентов и скриптов. Это не отдельная команда запуска — просто ssh ubuntu@IP. Аутентификация через пароль или ключ — отдельный шаг на стороне SSH-клиента.
• Отдельное ограничение — 10 запросов в минуту на сервер существует именно из-за чувствительности возвращаемых данных. Общий лимит платформы выше, но /ssh ограничивается жёстче.

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

• Переключить режим — PATCH /v1/infra/servers/:id/mode — перейти в OPEN/BLACKHOLE.
• Выполнить команду — POST /v1/infra/servers/:id/exec — SSH-эквивалент для BLACKHOLE.
• Загрузить файл — POST /v1/infra/servers/:id/upload — scp-эквивалент для BLACKHOLE.
• Политика доступа — кому видно приложение по HTTPS.