#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. On the reverse switch, the firewall is restored and the password is deleted. Switching to OPEN is forbidden if the platform (the openModeEnabled flag) or the portal (the allowOpenMode policy) does not permit it.

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 portal 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 — the platform admin does not bypass this check either. Then the portal policy allowOpenMode — the platform admin bypasses it. Only if both allow it is switching to OPEN possible.
• The IP does not change on switching. The cloud virtual machine stays the same — only the iptables rules and SSH configuration change.
• 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: 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. On switching, the accessPolicy value is preserved in the database — and starts taking effect again after returning to BLACKHOLE.

#See also

• SSH credentials — GET /v1/infra/servers/:id/ssh — get the password and command after switching to OPEN.
• Access policy — PATCH /v1/infra/servers/:id/access-policy — works only in BLACKHOLE.
• Deploy API — available only in BLACKHOLE.
• Get server — check the current mode.

#SSH credentials

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

Returns the SSH connection credentials. Full SSH access (with a password, private key, and public key) is returned only for servers in OPEN mode. For BLACKHOLE, all SSH fields are null: the server is closed behind the iptables firewall, and direct SSH is impossible. Instead of SSH, for BLACKHOLE use the Deploy API — /exec, /upload, /logs. Rate limit: up to 10 requests per minute per server.

#Parameters

#Examples

#curl — personal key

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

#curl — OAuth application

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

#JavaScript — personal key

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

if (data.mode === 'OPEN') {
  console.log('Command:', data.sshCommand)
  console.log('Password:', data.sshPassword)  // if it was issued
} else {
  console.log(data.note)  // BLACKHOLE — use the Deploy API
}

#JavaScript — OAuth application

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

#Response fields

#Response example

OPEN server:

{
  "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 server:

{
  "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.com",
    "note": "BLACKHOLE servers do not expose SSH. Use the Deploy API (exec/upload/logs) instead."
  }
}

#Error response example

404 — the server does not exist:

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

#Errors

The full list of common API errors — Errors.

#Known specifics

• Each BLACKHOLE → OPEN switch generates a new password. Old passwords (if any) become invalid. The same applies on the reverse cycle BLACKHOLE → OPEN → BLACKHOLE → OPEN: on every entry into OPEN, the platform generates a fresh sshPassword. The password is also returned in the response to PATCH /mode — you can save it from there.
• sshPrivateKey and sshPublicKey are returned only for keys generated by the platform. If, when creating the server via POST /v1/infra/servers, you passed your own sshPublicKey, the platform did not generate a private key — the sshPrivateKey field in the response will be null. Use your own private key on the client side.
• sshCommand is a ready "copy-paste" for AI agents and scripts. It is not a separate launch command — just ssh ubuntu@IP. Authentication via password or key is a separate step on the SSH client side.
• A separate limit — 10 requests per minute per server exists precisely because of the sensitivity of the returned data. The platform's overall limit is higher, but /ssh is throttled more strictly.

#See also

• Switch mode — PATCH /v1/infra/servers/:id/mode — switch to OPEN/BLACKHOLE.
• Execute command — POST /v1/infra/servers/:id/exec — the SSH equivalent for BLACKHOLE.
• Upload file — POST /v1/infra/servers/:id/upload — the scp equivalent for BLACKHOLE.
• Access policy — who sees the application via HTTPS.