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

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 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
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionBLACKHOLE server ID

Request fields (body)

Field Type Required Description
Fieldtype Typestring Requiredyes Descriptionuser — add a user, department — add a department
FielduserId Typestring Requiredyes (for type: "user") DescriptionBitrix24 user ID. Search via GET /b24-users?search=
FielduserName Typestring Requiredno DescriptionUser name (up to 255 characters). Optional, but recommended for readability in the UI
FielddepartmentId Typestring Requiredyes (for type: "department") DescriptionBitrix24 department ID
FielddepartmentName Typestring Requiredyes (for type: "department") DescriptionDepartment name (up to 255 characters)

Examples

curl — personal key

Terminal 
# 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

Terminal 
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
Fieldsuccess Typeboolean Descriptiontrue on successful addition. HTTP status — 201
Fielddata.id Typestring (UUID) DescriptionID of the created entry — pass it to DELETE /access/:accessId to delete it
Fielddata.serverId Typestring (UUID) DescriptionServer ID
Fielddata.userId Typestring DescriptionBitrix24 user ID (only for type: "user")
Fielddata.userName Typestring | null DescriptionUser name (only for type: "user")
Fielddata.networkUserId Typestring | null DescriptionThe user's Network ID. null right after creation, filled in asynchronously (only for type: "user")
Fielddata.departmentId Typestring DescriptionBitrix24 department ID (only for type: "department")
Fielddata.departmentName Typestring DescriptionDepartment name (only for type: "department")
Fielddata.grantedBy Typestring (UUID) DescriptionID of the Vibecode user who created the entry
Fielddata.createdAt Typestring (ISO 8601) DescriptionWhen 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
HTTP400 CodeVALIDATION_ERROR DescriptionThe fields failed validation: invalid type, a required field for the chosen type is missing
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 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe 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
HTTP404 CodeNOT_FOUND DescriptionThe server does not exist, was deleted, or belongs to another API key while you are not on its development team
HTTP409 CodeALREADY_EXISTS DescriptionAn entry for this userId/departmentId on this server already exists
HTTP429 CodeRATE_LIMITED DescriptionThe platform's overall request limit was exceeded

The full list of common API errors — 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.

See also