Access policy

PATCH /v1/infra/servers/:id/access-policy

Updates the access policy for a BLACKHOLE server — defines which Bitrix24 users can open the application via the HTTPS subdomain (app-{id}.vibecode.bitrix24.com). The default is OWNER_ONLY — only the API key owner. Works only in BLACKHOLE mode; for an OPEN server it returns BLACKHOLE_ONLY — first switch the mode via PATCH /mode.

Changing accessPolicy from OWNER_ONLY to a more open value directly affects security. Switching to PORTAL, AUTHENTICATED, or PUBLIC opens the application to other people. AI agents: never call this endpoint without explicit user confirmation.

Parameters

Request fields (body)

Values (from the most closed to the most open):

Examples

curl — personal key

curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "PORTAL"}'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "NAMED_USERS"}'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'NAMED_USERS' }),
  }
)
const { data } = await res.json()
console.log('New policy:', data.accessPolicy)

JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'OWNER_ONLY' }),
  }
)

Response fields

Response example

{
  "success": true,
  "data": {
    "accessPolicy": "PORTAL"
  }
}

Error response example

400 — the server is in OPEN mode:

{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Access policy is a Black Hole feature. Server is in OPEN mode — switch to BLACKHOLE via PATCH /v1/infra/servers/:id/mode first."
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• PUBLIC is especially dangerous. It makes the application accessible without any authentication — to any visitor from the internet. Policy changes are recorded in the Bitrix24 account's audit log.
• NAMED_USERS and DEPARTMENT require non-empty access lists. The policy change itself does not add users — the list is maintained separately via POST /access. If the list is empty under NAMED_USERS/DEPARTMENT, the application will be inaccessible to everyone except the owner (there is no automatic fallback to OWNER_ONLY).
• The new policy also applies to sessions that are already open. If it no longer admits a user, the application becomes unavailable to them within a minute. The exception is a switch to OWNER_ONLY: some open sessions keep working until they expire, up to 40 minutes, but can no longer be renewed. If you switch a server to OWNER_ONLY to close access immediately, allow for this delay.
• A policy change does not close access through share-url links. They are revoked separately — Revoke a token.
• When you switch back to OWNER_ONLY, the entries in /access stay in the database. They are not applied unless the policy is NAMED_USERS/DEPARTMENT. To clear the history, delete the entries via DELETE /access/:accessId.
• When you switch the mode to OPEN, accessPolicy does not change, but it is not applied either: in OPEN mode, protection is handled by SSH keys and iptables. On returning to BLACKHOLE, the policy becomes effective again.
• AUTHENTICATED includes non-members of the Bitrix24 account. Unlike PORTAL, AUTHENTICATED allows any authenticated Bitrix24 user (including those who are not members of your Bitrix24 account). It suits guest-form applications, but access is no longer limited to your own Bitrix24 account team.
• The API key owner always has access — they are not removed from the list on a policy change. To revoke your own access, you need a request from a different key.
• When the app is opened from the Bitrix24 catalog, the Bitrix24 account itself confirms membership. The employee needs no Vibecode account: an app with the PORTAL policy (as well as AUTHENTICATED and PUBLIC) opens for every employee, exactly as promised. The platform additionally checks with Bitrix24 that this is an active employee, not a former one and not an external guest. Identity-based policies (OWNER_ONLY, NAMED_USERS, DEPARTMENT) do not open through this path — they resolve access per individual, so the employee has to sign in to Vibecode once.

See also

• Access list
• Add user/department
• Delete access entry
• Search Bitrix24 users
• Switch mode