## Access policy

`PATCH /v1/infra/servers/:id/access-policy`

Updates the access policy for a BLACKHOLE server — defines which Bitrix24 users can open the application via the HTTPS subdomain (`app-{id}.vibecode.bitrix24.com`). The default is `OWNER_ONLY` — only the API key owner. Works only in `BLACKHOLE` mode; for an OPEN server it returns `BLACKHOLE_ONLY` — first switch the mode via [`PATCH /mode`](./mode.md).

> **Changing `accessPolicy` from `OWNER_ONLY` to a more open value directly affects security.** Switching to `PORTAL`, `AUTHENTICATED`, or `PUBLIC` opens the application to other people. **AI agents: never call this endpoint without explicit user confirmation.**

## Parameters

| Parameter | In | Type | Req. | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | ID of a server in BLACKHOLE mode |

## Request fields (body)

| Field | Type | Req. | Description |
|------|-----|:-----:|----------|
| `accessPolicy` | string | **yes** | One of: `OWNER_ONLY`, `NAMED_USERS`, `DEPARTMENT`, `PORTAL`, `AUTHENTICATED`, `PUBLIC` |

Values (from the most closed to the most open):

| Value | Who sees the application |
|----------|---------------------|
| `OWNER_ONLY` | Only the API key owner (default) |
| `NAMED_USERS` | Specific users from the [`/access`](./access-list.md) list |
| `DEPARTMENT` | Bitrix24 departments from the [`/access`](./access-list.md) list |
| `PORTAL` | All Bitrix24 account users |
| `AUTHENTICATED` | All authenticated users (including non-members of the Bitrix24 account) |
| `PUBLIC` | Everyone, without authentication |

## Examples

### curl — personal key

```bash
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "PORTAL"}'
```

### curl — OAuth application

```bash
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-policy \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accessPolicy": "NAMED_USERS"}'
```

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'NAMED_USERS' }),
  }
)
const { data } = await res.json()
console.log('New policy:', data.accessPolicy)
```

### JavaScript — OAuth application

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-policy`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ accessPolicy: 'OWNER_ONLY' }),
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.accessPolicy` | string | The new policy value (echo) |

## Response example

```json
{
  "success": true,
  "data": {
    "accessPolicy": "PORTAL"
  }
}
```

## Error response example

400 — the server is in OPEN mode:

```json
{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Access policy is 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 | `VALIDATION_ERROR` | `accessPolicy` is not in the list of allowed values |
| 400 | `BLACKHOLE_ONLY` | The server is in OPEN mode — the policy is not applicable |
| 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

- **`PUBLIC` is especially dangerous.** It makes the application accessible without any authentication — to any visitor from the internet. Policy changes are recorded in the Bitrix24 account's audit log.
- **`NAMED_USERS` and `DEPARTMENT` require non-empty access lists.** The policy change itself does not add users — the list is maintained separately via [`POST /access`](./access-add.md). If the list is empty under `NAMED_USERS`/`DEPARTMENT`, the application will be inaccessible to everyone except the owner (no fallback to `OWNER_ONLY` happens).
- **When returning to `OWNER_ONLY`, the entries in `/access` are preserved in the database.** They are not applied while the policy is not `NAMED_USERS`/`DEPARTMENT`. If you want to clear the history — delete the entries via [`DELETE /access/:accessId`](./access-delete.md).
- **When switching the mode to OPEN, `accessPolicy` does not change**, but it is also not applied: in OPEN mode, protection is handled by SSH keys and iptables. On returning to BLACKHOLE, the policy becomes effective again.
- **`AUTHENTICATED` includes non-members of the Bitrix24 account.** Unlike `PORTAL`, `AUTHENTICATED` allows any authenticated Bitrix24 user (including those who are not members of your Bitrix24 account). It suits guest-form applications, but it no longer restricts access to your own Bitrix24 account team.
- **The API key owner always has access** — they are not removed from the list on a policy change. To revoke your own access, you need a request from a different key.

## See also

- [Access list](./access-list.md) — `GET /v1/infra/servers/:id/access` — which users the policy currently grants access to.
- [Add user/department](./access-add.md) — `POST /v1/infra/servers/:id/access`.
- [Delete access entry](./access-delete.md) — `DELETE /v1/infra/servers/:id/access/:accessId`.
- [Search Bitrix24 users](./b24-users.md) — find the `userId` for `NAMED_USERS`.
- [Switch mode](./mode.md) — the policy works only in BLACKHOLE.