Access and modes

Managing application visibility and server mode. The access policy (accessPolicy) determines who in Bitrix24 can open the application's HTTPS subdomain: only the owner, a list of specific users and departments, all Bitrix24 account users, or any visitor at all. The server mode (mode) toggles between Black Hole (everything closed behind the firewall) and OPEN (direct access by IP).

Changing accessPolicy from OWNER_ONLY to a more open value directly affects security. Never do it on a user's behalf without explicit confirmation — it opens the application to other people in the Bitrix24 account or to the entire internet.

Scope: vibe:infra

Approving wider access

Widening application access on a protected Bitrix24 account requires human approval. The original operation returns 409 AUDIENCE_APPROVAL_REQUIRED and leaves access unchanged.

1. Find error.details.proposalId, approvalUrl, expiresAt and retryOperation in the original operation's response.
2. Send approvalUrl to a person who is authorized to approve access and signed in to their Vibecode account. An API key cannot approve the request.
3. Check the state with the original API key. Another key belonging to the same owner cannot access the request.
4. Once the state is APPROVED, retry the original operation with the same key, the exact same parameters and approvalId set to proposalId. Approval alone does not change access. The original method's page describes the retry format. The retryOperation object is not an HTTP request body.
5. Cancel the request if the change is no longer needed. Cancellation does not change access.

Even a key with the vibe:cowork scope can check and cancel its own request if its current permissions allow the operation. This does not grant permission to change infrastructure.

SSH credentials

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

Returns the SSH connection credentials. Full SSH credentials (password, private key, and public key) are returned only for servers in OPEN mode. A person switches OPEN mode on in the cabinet: PATCH /v1/infra/servers/:id/mode to OPEN answers 403 DIRECT_NETWORK_CHANGE_REQUIRES_HUMAN for any API key. For BLACKHOLE, sshPassword, sshPrivateKey, sshPublicKey, and sshCommand are null, while sshUser and sshPort are omitted: the server is closed off by an iptables firewall, and direct SSH is not possible. For BLACKHOLE, use the Deploy API instead of SSH — /exec, /upload, /logs. Rate limit: up to 10 requests per minute per server. The effective value is provided in the x-ratelimit-limit header.

HEAD is not supported at this address and returns 404. Use GET to retrieve SSH credentials.

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

For the full list of common API errors, see Errors.

Known specifics

• Each BLACKHOLE → OPEN switch generates a new password. Old passwords (if any) become invalid. The same applies to a back-and-forth cycle BLACKHOLE → OPEN → BLACKHOLE → OPEN: each time the server enters OPEN, the platform generates a fresh sshPassword.
• sshPrivateKey and sshPublicKey are the platform's key pair, not yours. The platform creates this key pair for every server, so in OPEN mode both fields are returned even if you passed your own sshPublicKey when creating the server via POST /v1/infra/servers. This request does not return your key: the platform does not store it. The platform installs your own key while the machine is being prepared, so you can connect with it once the server is switched to OPEN mode.
• sshCommand is a ready-to-copy string 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 of 10 requests per minute per server exists precisely because the returned data is sensitive. The effective value is provided in the x-ratelimit-limit header. The platform's overall limit is higher, but /ssh is throttled more strictly.

See also

• Switch mode
• Run a command
• Upload a file
• Access policy