Switch mode

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

Switches the server between BLACKHOLE mode (everything closed behind the firewall, access only via the HTTPS subdomain) and OPEN mode (direct access by IP, SSH on port 22 open). When switching to OPEN, the firewall is fully removed and an SSH password is generated. When switching back, the firewall is restored and the password is deleted. Switching to OPEN is forbidden if the platform (the openModeEnabled flag) or the Bitrix24 account (the allowOpenMode policy) does not permit it, or if the server's role requires a sealed network policy.

OPEN disables Black Hole protection. The server becomes reachable from the internet by IP. All Deploy API endpoints (/exec, /upload, /logs, /deploy) work only in BLACKHOLE mode — in OPEN they return an error.

Parameters

Request fields (body)

Examples

curl — personal key

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

# OPEN → BLACKHOLE (restore protection)
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/mode \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "BLACKHOLE"}'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/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 — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/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(`New SSH password: ${data.sshPassword}`)

JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/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' }),
  }
)

Response fields

Response example

BLACKHOLE → OPEN switch:

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

OPEN → BLACKHOLE switch:

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

Error response example

403 — switching to OPEN is forbidden by the Bitrix24 account policy:

{
  "success": false,
  "error": {
    "code": "OPEN_MODE_NOT_ALLOWED",
    "message": "OPEN mode is not allowed by portal policy",
    "userMessage": "OPEN mode is not allowed by Bitrix24 account policy. An admin enables it in Settings → Creation. Meanwhile, use the Deploy API (exec/upload/logs)."
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• OPEN resolution order (both levels must allow it): first the platform flag openModeEnabled — not even the platform admin bypasses this check. Then the Bitrix24 account policy allowOpenMode — the platform admin bypasses it. Switching to OPEN is possible only if both allow it.
• The IP does not change when the mode is switched. The cloud virtual machine stays the same — only the network policy and the SSH configuration change.
• The network policy is held by two layers. The inner one is the iptables rules on the machine itself; the outer one sits outside it and cannot be lifted from within. A mode switch changes both, the outer layer first. Where the outer layer is not supported for a server, only the inner one applies and the endpoint behaves as before.
• A connection loss mid-switch closes the firewall again. If the connection to the server is lost after the outer layer was switched, the platform closes the machine's firewall and restores the outer layer to its previous role, and only then returns the error. That closing travels over the same connection that was lost, so on a fully unreachable server it does not arrive either.
• A failed mode write after the server was closed does not reopen the firewall. The machine stays closed on both layers while the server record still reads OPEN. A retry with mode: "OPEN" returns 400 SAME_MODE. Access comes back by switching to BLACKHOLE and then to OPEN again.
• The tunnel (blackholeStatus) is preserved in OPEN mode. The Black Hole agent keeps running, the HTTPS subdomain stays operational — the firewall simply no longer blocks external traffic. However, the Deploy API still refuses the call: it requires BLACKHOLE specifically.
• accessPolicy is not applied in OPEN. In OPEN, protection is built on SSH keys and iptables (which is removed); the HTTPS subdomain policy effectively does not work. When the mode is switched, the accessPolicy value is preserved in the database — and starts taking effect again after returning to BLACKHOLE.

See also

• SSH credentials
• Access policy
• Deploy API
• Get server