## Изменить API-ключ

`PATCH /v1/keys/:id`

Изменяет настройки API-ключа владельца менеджмент-ключа. Тело плоское, без обёртки `fields`: передавайте только поля, которые меняются.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string | да | Идентификатор записи ключа. Список: [`GET /v1/keys`](/docs/management-keys/list) |

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `name` | string | нет | Название ключа, от 1 до 255 символов. Название только из пробелов не принимается |
| `scopes` | string[] | нет | Новый полный список [скоупов](/docs/scopes) ключа, не меньше одного. Набор прав проверяется так же, как при [создании](/docs/management-keys/create). Право `vibe:storage` добавляется только личному ключу. Ключу приложения и ключу неизвестного происхождения его можно прислать без изменения или снять |
| `status` | string | нет | `ACTIVE` — вернуть ключ в работу, `REVOKED` — отозвать |
| `mode` | string | нет | Режим доступа ключа: `READWRITE` или `READONLY`. Подробнее — [Режим доступа](/docs/keys-auth/access-mode). Перевод в `READWRITE` запрещён, если политика портала требует `READONLY` |
| `ipWhitelist` | string[] | нет | Разрешённые IP-адреса. Пустой массив снимает ограничение |
| `expiresAt` | string \| null | нет | Дата окончания срока действия в формате ISO 8601. `null` — бессрочный ключ |
| `rateLimit` | number \| null | нет | Индивидуальный лимит запросов к AI-эндпоинтам. Принимается только текущее значение ключа: изменение отвечает `403 RATE_LIMIT_ADMIN_ONLY` |
| `totalDefault` | boolean \| null | нет | Приходит ли `meta.total` в списках, запрошенных этим ключом. `null` — действует настройка платформы |

## Примеры

Запрос принимает только менеджмент-ключ — см. [Ограничения](/docs/management-keys#ограничения).

### curl — менеджмент-ключ

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Интеграция с CRM и задачами"
  }'
```

### JavaScript — менеджмент-ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Интеграция с CRM и задачами',
  }),
})

const { success, data } = await res.json()
console.log('Ключ:', data.name, '—', data.status)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string | Идентификатор записи ключа |
| `data.name` | string | Название ключа |
| `data.prefix` | string | Первые символы значения ключа |
| `data.suffix` | string | Последние четыре символа значения ключа |
| `data.type` | string | Тип записи ключа, всегда `APP` |
| `data.userId` | string | Идентификатор владельца ключа |
| `data.portalId` | string | Идентификатор портала |
| `data.clientId` | string \| null | Идентификатор клиента OAuth, если он записан на ключе. Иначе `null` |
| `data.scopes` | array | [Скоупы](/docs/scopes) ключа после изменения |
| `data.ipWhitelist` | array | Разрешённые IP-адреса. Пустой массив — без ограничения |
| `data.expiresAt` | string \| null | Дата окончания срока действия (ISO 8601), `null` — бессрочный |
| `data.rateLimit` | number \| null | Индивидуальный лимит запросов к AI-эндпоинтам, `null` — общий лимит платформы |
| `data.status` | string | `ACTIVE`, `REVOKED`, `EXPIRED` или `BLOCKED` |
| `data.lastUsedAt` | string \| null | Дата последнего запроса этим ключом (ISO 8601) |
| `data.createdAt` | string | Дата создания (ISO 8601) |
| `data.updatedAt` | string | Дата последнего изменения (ISO 8601) |
| `data.accessMode` | string | `READWRITE` или `READONLY` |
| `data.totalDefault` | boolean \| null | Приходит ли `meta.total` в списках, запрошенных этим ключом. `null` — действует настройка платформы |
| `data.issuedVia` | string \| null | Канал, которым выписан вебхук ключа: `per-portal` и `cloud-shared` — модуль-коннектор на портале, `dev_key` — ключ разработчика владельца, `legacy` — регистрация через Битрикс24 Network, `none` — вебхук не заводился. `null`, если канал не записан |

Поля `b24Ready` в ответе нет. Узнать его можно запросом [`GET /v1/keys/:id`](/docs/management-keys/get).

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

```json
{
  "success": true,
  "data": {
    "id": "6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc",
    "name": "Интеграция с CRM и задачами",
    "prefix": "vibe_api_XXXXXXXXX",
    "suffix": "XXXX",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm", "task", "tasks", "im"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": "2026-10-28T13:11:06.013Z",
    "createdAt": "2026-05-18T10:22:10.950Z",
    "updatedAt": "2026-10-29T12:16:49.962Z",
    "accessMode": "READWRITE",
    "totalDefault": null,
    "issuedVia": null
  }
}
```

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

403 — ключу авторизации приложения добавляется право Битрикс24:

```json
{
  "success": false,
  "error": {
    "code": "OAUTH_SCOPE_CHANGE_REQUIRES_REISSUE",
    "message": "Набор прав OAuth-приложения нельзя изменить у существующего ключа — права фиксируются при выдаче. Создайте новый ключ авторизации с нужным набором прав."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | Поле тела не прошло проверку: название из пробелов или длиннее 255 символов, неизвестное значение `status`, `mode` или скоупа, пустой список `scopes`, некорректный IP-адрес, `rateLimit` вне диапазона от 1 до 100 000 |
| 400 | `INVALID_JSON_BODY` | Тело запроса — некорректный JSON |
| 400 | `PERSONAL_KEY_WEBHOOK_SCOPES_INVALID` | Новый список `scopes` не содержит ни одного права на данные: остались только `placement`, `entity` и `userfieldtype`. Проверка идёт до обращения к порталу |
| 400 | `PERSONAL_KEY_WEBHOOK_SCOPES_INVALID` | Портал отказался сохранить на вебхуке ключа все права Битрикс24 из нового списка. Права ключа не меняются |
| 400 | `INVALID_SCOPES` | Часть новых прав недоступна на портале. Права ключа не меняются |
| 400 | `BOX_NO_DEVELOPER_KEY` | Права Битрикс24 меняются на портале, где они проверяются на стороне Битрикс24, а у владельца ключа нет ключа разработчика. Права ключа не меняются |
| 402 | `ACCOUNT_FROZEN` | Баланс аккаунта заморожен. Запрос, в теле которого только `{"status": "REVOKED"}`, проходит и на замороженном аккаунте |
| 403 | `KEY_BLOCKED` | Ключ заблокирован (`status: BLOCKED`) и не изменяется. Заменить его можно только [перевыпуском](/docs/management-keys/rotate) |
| 403 | `RATE_LIMIT_ADMIN_ONLY` | Запрос меняет `rateLimit`. Индивидуальный лимит через этот эндпоинт не меняется |
| 403 | `KEY_POLICY_READONLY_REQUIRED` | Запрос переводит ключ в `READWRITE`, а политика портала требует для ключей `READONLY`. Исключение для отдельного ключа выдаёт администратор портала |
| 403 | `OAUTH_SCOPE_CHANGE_REQUIRES_REISSUE` | Ключу авторизации приложения (`vibe_app_`) добавляется право Битрикс24. Права такого ключа фиксируются при выдаче — создайте новый ключ авторизации с нужным набором. Снятие прав проходит |
| 403 | `KEY_STORAGE_SCOPE_REQUIRES_PERSONAL_KEY` | Новый список добавляет `vibe:storage` ключу приложения или ключу неизвестного происхождения. Создайте новый личный ключ с правом хранилища |
| 403 | `INFRA_DISABLED_FOR_PORTAL` | Новый список добавляет право `vibe:infra`, которого у ключа не было, а администратор портала выключил работу с серверами. Права ключа не меняются. Правка ключа, который это право уже несёт, проходит и на закрытом портале, снятие права разрешено всегда |
| 403 | `ONEC_ACCESS_REQUIRED` | Новый список добавляет право `vibe:onec`, которого у ключа не было, а у владельца ключа нет доступа к 1С. Проверяется доступ владельца, а не того, кто отправил запрос. Права ключа не меняются. Правка ключа, который это право уже несёт, проходит без проверки |
| 403 | `SCOPE_NOT_AVAILABLE_ON_PORTAL` | Новый список добавляет право, которое на этом портале не выдаётся. Сообщение называет такие права |
| 403 | `SYSTEM_KEY_REACTIVATE_FORBIDDEN` | Запрос переводит в `ACTIVE` или продлевает срок ключа, который платформа выдаёт на своём эндпоинте: настольного приложения Cowork/Code, агента, проектного ключа для деплоя. В тексте ответа сказано, где этот ключ выдаётся заново |
| 403 | `COWORK_PLATFORM_DISABLED` | Ключ, оплачиваемый подпиской Cowork/Code, переводится в `ACTIVE` или продлевается, а Cowork/Code отключён на уровне платформы |
| 403 | `COWORK_ACCESS_REQUIRED` | То же для ключа подписки: владельцу ключа доступ к Cowork/Code не открыт |
| 403 | `COWORK_EXTERNAL_CLIENTS_DISABLED` | То же для ключа подписки: администратор портала запретил сторонние клиенты |
| 403 | `COWORK_SUBSCRIPTION_INACTIVE` | То же для ключа подписки: подписка Cowork/Code приостановлена или отменена |
| 403 | `COWORK_SEAT_KEY_MODE_CABINET_ONLY` | Запрос меняет `mode` ключа настольного приложения Cowork/Code. Это режим всего места, и меняется он в кабинете, где видно, что сузится вместе с ним |
| 403 | `COWORK_KEY_MODE_ABOVE_SEAT` | Запрос поднимает `mode` ключа стороннего агента на подписке Cowork/Code выше режима места. Сначала расширяют место, в его пределах правка проходит. Тот же код приходит, если место сузили, пока выполнялся запрос |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Менеджмент-ключ, которым отправлен запрос, работает в режиме `READONLY` |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | У менеджмент-ключа нет скоупа `vibe:mgmt:keys` |
| 404 | `KEY_NOT_FOUND` | Ключа с таким `id` нет, он принадлежит другому пользователю или это менеджмент-ключ |
| 409 | `REISSUE_IN_PROGRESS` | Только ключ авторизации (`vibe_app_`): запрос меняет `mode`, `status` или `expiresAt`, а с ключом этого приложения уже идёт другая операция — перевыпуск, изменение или удаление. Ключ не меняется, повторите запрос после её завершения |
| 409 | `KEY_NOT_ACTIVE` | Только ключ авторизации (`vibe_app_`): ключ уже не действует или изменился после начала запроса — например, его отозвали или удалили. Смена `mode` у отозванного ключа авторизации тоже отвечает этим кодом. Ключ не меняется. Перечитайте его через [`GET /v1/keys/:id`](/docs/management-keys/get) |
| 409 | `KEY_MANAGES_FOREIGN_SERVER` | Отзыв ключа, который управляет живым сервером другого владельца, сервером без владельца или сервером того же владельца на другом портале. Установите владельца и нужный портал сервера, затем перепривяжите его к ключу этого владельца в том же портале и повторите отзыв |
| 409 | `KEY_OPERATION_IN_PROGRESS` | Перенос, отзыв или конкурентная правка прав ключа ещё не завершены. Перечитайте ключ и повторите правку по свежему набору прав |
| 409 | `PORTAL_ADDRESS_CHANGED` | Коробочный портал переехал на новый адрес, а вебхук ключа выписан на прежний. Запрос к порталу не отправляется, права ключа не меняются ни на платформе Вайбкод, ни в Битрикс24. Переподключите ключ и повторите правку — порядок описан в статье [Авторизация, ключи и права](/docs/errors/auth#portal_address_changed-409) |
| 410 | `STALE_DEVELOPER_KEY` | Ключ разработчика владельца недействителен и автоматически не перевыпускается. Права ключа не меняются. Переподключите аккаунт |
| 502 | `RECOVERY_FAILED` | Перевыпуск ключа разработчика не удался, состояние временное — повторите запрос |
| 502 | `DEVKEY_SCOPE_SYNC_FAILED` | Битрикс24 не принял новые права вебхука ключа. Диагностика — в `error.details`. Права ключа не меняются |
| 502 | `BITRIX_UNAVAILABLE` | Не удалось передать в Битрикс24 смену статуса ключа |
| 401 | `WRONG_KEY_TYPE` | Запрос отправлен ключом портала — личным `vibe_api_` или ключом авторизации `vibe_app_`. Эндпоинт принимает только менеджмент-ключ |
| 401 | `KEY_INACTIVE` | Менеджмент-ключ отозван или заблокирован |
| 401 | `KEY_EXPIRED` | Срок действия менеджмент-ключа закончился |
| 401 | `INVALID_API_KEY` | Ключ с переданным значением не найден |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Отказы `OWNER_DELETED`, `OWNER_BLOCKED` и `ACCOUNT_PENDING_ERASURE` зависят от аккаунта владельца ключа — см. [Состояние аккаунта владельца](/docs/management-keys#состояние-аккаунта-владельца).

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

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

**Режим доступа меняется полем `mode`.** Поле `accessMode` из ответа в теле запроса не принимается: запрос с ним отвечает `200`, режим ключа не меняется.

**Значение, равное текущему, изменением не считается.** Клиент может прислать запись ключа целиком ради переименования: тот же `mode`, тот же `rateLimit` и тот же набор `scopes` проходят без проверок, которые срабатывают на смену этих полей.

**Права и статус меняются и в Битрикс24.** Если права ключа проверяются на стороне Битрикс24, новый набор сначала передаётся на вебхук ключа и только после этого сохраняется в Вайбкод. При отказе портала ключ остаётся с прежними правами. При отзыве платформа удаляет вебхук ключа в Битрикс24 либо отключает его учётные данные.

**Отзыв гасит выписанные ключом токены доступа.** Вместе с переводом в `REVOKED` отзываются [токены доступа](/docs/infra/access-tokens) к серверам, выписанные этим ключом.

**Ключи, выданные платформой, проверяются только на возврате в работу и продлении.** Сужение срока, отзыв и правка остальных полей таких ключей работают без проверок выдачи. Обычных ключей кабинета эти проверки не касаются.

**Режим ключей Cowork/Code живёт на месте.** Место — пара сотрудника и портала, общая для всех его устройств. Поэтому `mode` ключа настольного приложения здесь не меняется, а у ключа стороннего агента на подписке ограничен режимом места.

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

- [Список API-ключей портала](/docs/management-keys/list)
- [Создать API-ключ](/docs/management-keys/create)
- [Получить API-ключ](/docs/management-keys/get)
- [Удалить API-ключ](/docs/management-keys/delete)
- [Перевыпустить API-ключ](/docs/management-keys/rotate)
- [Режим доступа](/docs/keys-auth/access-mode)
- [Скоупы](/docs/scopes)
- [Менеджмент-ключи](/docs/management-keys)