## Добавить пользователя или отдел

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

Добавляет запись доступа к BLACKHOLE-серверу: конкретного пользователя Битрикс24 (при политике `NAMED_USERS`) или отдел (при политике `DEPARTMENT`). Политика при этом не меняется автоматически — смените её через [`PATCH /access-policy`](./access-policy.md) отдельно, если ещё не переключали. Дубликаты (тот же `userId` или `departmentId` на том же сервере) возвращают 409 `ALREADY_EXISTS`.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера |

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `type` | string | **да** | `user` — добавить пользователя, `department` — добавить отдел |
| `userId` | string | да (для `type: "user"`) | ID пользователя Битрикс24. Ищите через [`GET /b24-users?search=`](./b24-users.md) |
| `userName` | string | нет | Имя пользователя (до 255 символов). Опционально, но рекомендуется для удобства чтения в UI |
| `departmentId` | string | да (для `type: "department"`) | ID отдела Битрикс24 |
| `departmentName` | string | да (для `type: "department"`) | Имя отдела (до 255 символов) |

## Примеры

### curl — личный ключ

```bash
# Добавить пользователя
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "userId": "243", "userName": "Катя Иванова"}'

# Добавить отдел
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "department", "departmentId": "5", "departmentName": "Разработка"}'
```

### curl — OAuth-приложение

```bash
curl -X POST https://vibecode.bitrix24.tech/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": "Катя Иванова"}'
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/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: 'Катя Иванова',
    }),
  }
)
if (res.status === 201) {
  const { data } = await res.json()
  console.log(`Добавлен: ${data.userName} (запись ${data.id})`)
}
```

### JavaScript — OAuth-приложение

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/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: 'Разработка',
    }),
  }
)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном добавлении. HTTP-статус — 201 |
| `data.id` | string (UUID) | ID созданной записи — передавайте в [`DELETE /access/:accessId`](./access-delete.md) для удаления |
| `data.serverId` | string (UUID) | ID сервера |
| `data.userId` | string | ID пользователя Битрикс24 (только для `type: "user"`) |
| `data.userName` | string \| null | Имя пользователя (только для `type: "user"`) |
| `data.networkUserId` | string \| null | Network ID пользователя. `null` сразу после создания, заполняется асинхронно (только для `type: "user"`) |
| `data.departmentId` | string | ID отдела Битрикс24 (только для `type: "department"`) |
| `data.departmentName` | string | Имя отдела (только для `type: "department"`) |
| `data.grantedBy` | string (UUID) | ID пользователя Вайбкод, который создал запись |
| `data.createdAt` | string (ISO 8601) | Момент добавления |

## Пример ответа

Добавление пользователя:

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

Добавление отдела:

```json
{
  "success": true,
  "data": {
    "id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "departmentId": "5",
    "departmentName": "Разработка",
    "grantedBy": "f1d2e3c4-5b6a-4d0e-8f1a-2b3c4d5e6f70",
    "createdAt": "2026-04-22T11:30:00.000Z"
  }
}
```

## Пример ответа при ошибке

409 — запись уже существует:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | Поля не прошли валидацию: неверный `type`, отсутствует обязательное поле для выбранного типа |
| 400 | `BLACKHOLE_ONLY` | Сервер в режиме OPEN |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `NOT_FOUND` | Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 409 | `ALREADY_EXISTS` | Запись для этого `userId`/`departmentId` на этом сервере уже существует |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **`userName` и `departmentName` — только для отображения.** Для сопоставления при проверке доступа используются `userId`/`departmentId` — имя на авторизацию не влияет. Имя используется для отображения в списке, когда интеграция с Битрикс24 временно недоступна.
- **`networkUserId` заполняется асинхронно.** Сразу после `POST` поле `null`. В фоне платформа вызывает веб-хук Битрикс24 (если доступен), находит Network ID пользователя и обновляет запись. Это нужно для сопоставления, когда пользователь входит в Вайбкод через Network OAuth (а не через ваш портал).
- **Уникальность — пара `(serverId, userId)` для пользователей и `(serverId, departmentId)` для отделов.** Чтобы «обновить» запись — сначала `DELETE`, потом `POST`.
- **Политика не меняется автоматически.** Если сервер в `OWNER_ONLY`, добавление записи не сработает как «открытие доступа» — сначала переключите политику на `NAMED_USERS` (или `DEPARTMENT`) через [`PATCH /access-policy`](./access-policy.md).

## Смотрите также

- [Список доступа](./access-list.md)
- [Удалить запись](./access-delete.md)
- [Политика доступа](./access-policy.md)
- [Поиск пользователей Битрикс24](./b24-users.md)