For AI agents: markdown of this page — /docs-content-en/infra/access/access-list.md documentation index — /llms.txt

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

Parameter In Type Req. Description
id path string (UUID) yes BLACKHOLE server ID

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
success boolean Always true on success
data.users array User access entries, sorted by createdAt (newest first)
data.users[].id string (UUID) ID of the entry in the table — needed for DELETE
data.users[].userId string Bitrix24 user ID
data.users[].userName string | null User name (optional, filled in on addition)
data.users[].networkUserId string | null The user's Network ID — filled in asynchronously after addition; used for matching when signing in via a Vibecode session
data.users[].grantedBy string (UUID) ID of the Vibecode user who created the entry
data.users[].createdAt string (ISO 8601) When the entry was added
data.departments array Department access entries
data.departments[].id string (UUID) ID of the entry — needed for DELETE
data.departments[].departmentId string Bitrix24 department ID
data.departments[].departmentName string Department name (required on addition)
data.departments[].grantedBy string (UUID) ID of the Vibecode user who created the entry
data.departments[].createdAt string (ISO 8601) When the entry was added

Response example

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

JSON 
{
  "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

HTTP Code Description
400 BLACKHOLE_ONLY The server is in OPEN mode
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired API key
403 SERVER_ROLE_FORBIDDEN You are on this server's development team with the Developer role, and this operation is open to the Administrator role. error.hint carries your role, the required threshold and the list of calls that are open to you. Role breakdown — List servers
404 NOT_FOUND The server does not exist, was deleted, or belongs to another API key while you are not on its development team
429 RATE_LIMITED The platform's overall request limit was exceeded

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