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 Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionBLACKHOLE 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.users Typearray DescriptionUser access entries, sorted by createdAt (newest first)
Fielddata.users[].id Typestring (UUID) DescriptionID of the entry in the table — needed for DELETE
Fielddata.users[].userId Typestring DescriptionBitrix24 user ID
Fielddata.users[].userName Typestring | null DescriptionUser name (optional, filled in on addition)
Fielddata.users[].networkUserId Typestring | null DescriptionThe user's Network ID — filled in asynchronously after addition; used for matching when signing in via a Vibecode session
Fielddata.users[].grantedBy Typestring (UUID) DescriptionID of the Vibecode user who created the entry
Fielddata.users[].createdAt Typestring (ISO 8601) DescriptionWhen the entry was added
Fielddata.departments Typearray DescriptionDepartment access entries
Fielddata.departments[].id Typestring (UUID) DescriptionID of the entry — needed for DELETE
Fielddata.departments[].departmentId Typestring DescriptionBitrix24 department ID
Fielddata.departments[].departmentName Typestring DescriptionDepartment name (required on addition)
Fielddata.departments[].grantedBy Typestring (UUID) DescriptionID of the Vibecode user who created the entry
Fielddata.departments[].createdAt Typestring (ISO 8601) DescriptionWhen 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
HTTP400 CodeBLACKHOLE_ONLY DescriptionThe server is in OPEN mode
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeSERVER_ROLE_FORBIDDEN DescriptionYou 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
HTTP404 CodeNOT_FOUND DescriptionThe server does not exist, was deleted, or belongs to another API key while you are not on its development team
HTTP429 CodeRATE_LIMITED DescriptionThe 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