#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 (no fallback to OWNER_ONLY happens).
• When returning to OWNER_ONLY, the entries in /access are preserved in the database. They are not applied while the policy is not NAMED_USERS/DEPARTMENT. If you want to clear the history — delete the entries via DELETE /access/:accessId.
• When switching the mode to OPEN, accessPolicy does not change, but it is also not applied: 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 it no longer restricts access 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.

#See also

• Access list — GET /v1/infra/servers/:id/access — which users the policy currently grants access to.
• Add user/department — POST /v1/infra/servers/:id/access.
• Delete access entry — DELETE /v1/infra/servers/:id/access/:accessId.
• Search Bitrix24 users — find the userId for NAMED_USERS.
• Switch mode — the policy works only in BLACKHOLE.

#Access list

GET /v1/infra/servers/:id/access

Returns the list of Bitrix24 users and departments with access to the application. It applies when accessPolicy is set to NAMED_USERS (the user list) or DEPARTMENT (the department list). Works only for BLACKHOLE servers. Under OWNER_ONLY, PORTAL, AUTHENTICATED, PUBLIC, the lists are preserved in the database but are not applied.

#Parameters

#Examples

#curl — personal key

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

#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/access

#JavaScript — personal key

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

console.log(`Users: ${data.users.length}`)
console.log(`Departments: ${data.departments.length}`)

#JavaScript — OAuth application

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

#Response fields

#Response example

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60",
        "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
        "userId": "243",
        "userName": "Kate Smith",
        "networkUserId": "net_90126",
        "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
        "createdAt": "2026-04-20T10:15:00.000Z"
      }
    ],
    "departments": [
      {
        "id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
        "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
        "departmentId": "5",
        "departmentName": "Development",
        "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
        "createdAt": "2026-04-20T11:30:00.000Z"
      }
    ]
  }
}

#Error response example

400 — the server is in OPEN mode:

{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Access lists are 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

• Both collections are returned regardless of the current policy. You can maintain a user list and a department list in parallel, and switch the active policy via PATCH /access-policy later.
• networkUserId is filled in asynchronously. In the first seconds after POST /access the field may be null — then a background request to Bitrix24 sets the Network ID (it is needed for Vibecode sessions, if the user signs in to Vibecode via a Vibecode login rather than via Bitrix24 OAuth).
• grantedBy is the ID of a Vibecode user, not a Bitrix24 one. It corresponds to User.id in the platform database, not to userId on the Bitrix24 account. If the entry was created from the UI — it is the caller; if via an API key — the key owner.
• The list is not paginated and has no enforced limit. The endpoint returns all BlackHoleAccess and BlackHoleDepartment entries for the server. In practice the count is in the dozens: the list is filled in manually via POST /access.

#See also

• Add user/department — POST /v1/infra/servers/:id/access.
• Delete entry — DELETE /v1/infra/servers/:id/access/:accessId (this is where the id from the response is used).
• Access policy — switch NAMED_USERS / DEPARTMENT.
• Search Bitrix24 users — find the userId.