## 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`](./access-policy.md) 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

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

### curl — OAuth application

```bash
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`](./access-delete.md) |
| `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`](./access-delete.md) |
| `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 |
| 404 | `NOT_FOUND` | The server does not exist, was deleted, or belongs to another API key |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/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`](./access-policy.md) later.
- **`networkUserId` is filled in asynchronously.** In the first seconds after [`POST /access`](./access-add.md) 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`](./access-add.md).

## See also

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