Switch mode

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

Switches a server from OPEN mode back to the protected BLACKHOLE mode: the firewall is restored and the SSH password is deleted. A server cannot be switched to OPEN through the API; a person does that in the Vibecode dashboard.

A request with mode: "OPEN" is refused before any action on the server or its network. While OPEN mode is disabled platform-wide, the response is 403 OPEN_MODE_DISABLED, and nobody can switch a server to OPEN at that time, including from the dashboard. When the mode is enabled platform-wide, the response is 403 DIRECT_NETWORK_CHANGE_REQUIRES_HUMAN with a link to the server card in the dashboard.

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

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

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: 'BLACKHOLE' }),
  }
)
const { data } = await res.json()
console.log(`Server mode: ${data.mode}`)

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

OPEN → BLACKHOLE switch:

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

Error response example

403 — a request to switch to OPEN while the mode is enabled platform-wide:

{
  "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.com/servers/3f2b9c1e-7a4d-4e8b-9c5f-1d2e3a4b5c6d"
    }
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• In the dashboard, switching to OPEN goes through three checks. OPEN mode is enabled platform-wide, the Bitrix24 account is on a commercial plan, and the account allows OPEN through the allowOpenMode policy.
• The "Switch to OPEN" link is not always shown. It sits in the SSH block of the "Deploy" tab while the server is in running status and the Black Hole agent is CONNECTED. While OPEN mode is disabled platform-wide, the link is absent and the block shows an explanation instead.
• 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. The close command travels over the same connection that was lost, so it does not reach a fully unreachable server 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.
• The tunnel (blackholeStatus) is preserved in OPEN mode. The Black Hole agent keeps running, the HTTPS subdomain stays operational, and the firewall 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