## Add user or department

`POST /v1/infra/servers/:id/access`

Adds an access entry to a BLACKHOLE server: a specific Bitrix24 user (with the `NAMED_USERS` policy) or a department (with the `DEPARTMENT` policy). The policy is not changed automatically — switch it separately via [`PATCH /access-policy`](./access-policy.md) if you have not done so yet. Duplicates (the same `userId` or `departmentId` on the same server) return 409 `ALREADY_EXISTS`.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | BLACKHOLE server ID |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `type` | string | **yes** | `user` — add a user, `department` — add a department |
| `userId` | string | yes (for `type: "user"`) | Bitrix24 user ID. Search via [`GET /b24-users?search=`](./b24-users.md) |
| `userName` | string | no | User name (up to 255 characters). Optional, but recommended for readability in the UI |
| `departmentId` | string | yes (for `type: "department"`) | Bitrix24 department ID |
| `departmentName` | string | yes (for `type: "department"`) | Department name (up to 255 characters) |

## Examples

### curl — personal key

```bash
# Add a user
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "userId": "243", "userName": "Kate Smith"}'

# Add a department
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "department", "departmentId": "5", "departmentName": "Development"}'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "userId": "243", "userName": "Kate Smith"}'
```

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'user',
      userId: '243',
      userName: 'Kate Smith',
    }),
  }
)
if (res.status === 201) {
  const { data } = await res.json()
  console.log(`Added: ${data.userName} (entry ${data.id})`)
}
```

### JavaScript — OAuth application

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'department',
      departmentId: '5',
      departmentName: 'Development',
    }),
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on successful addition. HTTP status — 201 |
| `data.id` | string (UUID) | ID of the created entry — pass it to [`DELETE /access/:accessId`](./access-delete.md) to delete it |
| `data.serverId` | string (UUID) | Server ID |
| `data.userId` | string | Bitrix24 user ID (only for `type: "user"`) |
| `data.userName` | string \| null | User name (only for `type: "user"`) |
| `data.networkUserId` | string \| null | The user's Network ID. `null` right after creation, filled in asynchronously (only for `type: "user"`) |
| `data.departmentId` | string | Bitrix24 department ID (only for `type: "department"`) |
| `data.departmentName` | string | Department name (only for `type: "department"`) |
| `data.grantedBy` | string (UUID) | ID of the Vibecode user who created the entry |
| `data.createdAt` | string (ISO 8601) | When the entry was added |

## Response example

Adding a user:

```json
{
  "success": true,
  "data": {
    "id": "b3a6f8d1-3c2a-4e17-9f0b-1a7c2d4e5f60",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "userId": "243",
    "userName": "Kate Smith",
    "networkUserId": null,
    "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
    "createdAt": "2026-04-22T10:15:00.000Z"
  }
}
```

Adding a department:

```json
{
  "success": true,
  "data": {
    "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-22T11:30:00.000Z"
  }
}
```

## Error response example

409 — the entry already exists:

```json
{
  "success": false,
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Access entry already exists"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | The fields failed validation: invalid `type`, a required field for the chosen type is missing |
| 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` | The key is not recognized — no such key exists on the platform |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-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](/docs/infra/servers/list) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key does not change Bitrix24 data, and the request widens the set of employees who open the server's app, and that app has its own handler. Everyone who opens it passes their tokens to that handler |
| 404 | `NOT_FOUND` | The server does not exist, was deleted, or belongs to another API key while you are not on its development team |
| 409 | `ALREADY_EXISTS` | An entry for this `userId`/`departmentId` on this server already exists |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **`userName` and `departmentName` are for display only.** The access check matches on `userId`/`departmentId` — the name does not affect authorization. The name is used for display in the list when the Bitrix24 integration is temporarily unavailable.
- **`networkUserId` is filled in asynchronously.** Right after the `POST`, the field is `null`. In the background, the platform calls the Bitrix24 webhook (if available), finds the user's Network ID, and updates the entry. This is needed for matching when the user signs in to Vibecode via Network OAuth (rather than through your Bitrix24 account).
- **Uniqueness — the pair `(serverId, userId)` for users and `(serverId, departmentId)` for departments.** To "update" an entry, first `DELETE`, then `POST`.
- **The policy is not changed automatically.** If the server is in `OWNER_ONLY`, adding an entry will not act as "opening access" — first switch the policy to `NAMED_USERS` (or `DEPARTMENT`) via [`PATCH /access-policy`](./access-policy.md).

## See also

- [Access list](./access-list.md)
- [Delete entry](./access-delete.md)
- [Access policy](./access-policy.md)
- [Search Bitrix24 users](./b24-users.md)