Перевыпустить API-ключ

POST /v1/keys/:id/rotate

Выпускает новый API-ключ взамен прежнего с теми же настройками и переносит на него привязки прежнего ключа.

Параметры

Тело запроса может быть пустым или {}: поля тела не читаются, настройки нового ключа берутся с прежнего.

Примеры

Запрос принимает только менеджмент-ключ — см. Ограничения.

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

curl -X POST "https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc/rotate" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc/rotate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
  },
})

const { success, data, error } = await res.json()
if (success) {
  // Значение нового ключа приходит только в этом ответе
  console.log('Новый ключ:', data.rawKey)
} else if (error.details?.orphanKeyId) {
  // Замена отменена, порядок действий — в «Известных особенностях»
  console.error(error.code, error.details)
}

Поля ответа

Полей prefix, suffix и b24Ready в ответе нет — они приходят в GET /v1/keys/:id.

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

201 — новый ключ выпущен:

{
  "success": true,
  "data": {
    "id": "9b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "name": "Интеграция с CRM",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": null,
    "createdAt": "2026-10-29T12:22:53.937Z",
    "updatedAt": "2026-10-29T12:22:53.937Z",
    "accessMode": "READONLY",
    "totalDefault": null,
    "issuedVia": "cloud-shared",
    "rawKey": "vibe_api_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

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

409 — прежний ключ уже отозван:

{
  "success": false,
  "error": {
    "code": "KEY_NOT_ACTIVE",
    "message": "Key is no longer active"
  }
}

Ошибки

Остальные отказы выписки у перевыпуска те же, что у создания: оба метода выписывают ключ одним путём. Это отказы выписки со статусом 409, 410 и 502, со статусом 503 — NETWORK_DEVKEY_REQUIRED и CONNECTOR_KEY_ISSUE_TIMEOUT, а со статусом 403 — B24_MARKET_TRIAL_USED, B24_INSUFFICIENT_SCOPE, B24_ACCESS_DENIED и CONNECTOR_KEY_ISSUE_FORBIDDEN. Их описания и поле error.reason — в Создать API-ключ. Статус 503 приходит и от выписки, и от проверки адреса портала, поэтому решайте по коду, а не по статусу: PORTAL_ORIGIN_CUTOVER_UNAVAILABLE из таблицы выше можно повторить позже, а CONNECTOR_KEY_ISSUE_TIMEOUT сразу повторять нельзя — вебхук на портале мог уже появиться. Проверка доступа портала к платформе на перевыпуск не распространяется, поэтому 402 MARKETPLACE_REQUIRED, 402 INT_TARIFF_REQUIRED, 403 PORTAL_TARIFF_UNREADABLE и 403 PORTAL_SUBSCRIPTION_UNREADABLE здесь не приходят. Со статусом 402 до перевыпуска доходит только отказ самого Битрикс24 в выписке по тарифу — BY_PAID_ONLY, KZ_PAID_ONLY, UZ_PAID_ONLY, B24_PAID_TARIFF_REQUIRED.

Отказы OWNER_DELETED, OWNER_BLOCKED, ACCOUNT_PENDING_ERASURE и B24_USER_DELETED зависят от аккаунта владельца ключа — см. Состояние аккаунта владельца.

Полный список общих ошибок API — Ошибки.

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

Что переносится на новый ключ. Название, права, разрешённые IP-адреса, режим доступа, индивидуальный лимит и настройка totalDefault переносятся с прежнего ключа как есть. Серверы, приложения, токены доступа, операции деплоя и боты прежнего ключа переезжают на новый. Срок действия не переносится: новый ключ бессрочный.

Переходный период прежнего ключа — до 24 часов. Прежний ключ продолжает работать 24 часа после перевыпуска, затем перестаёт действовать. Если его собственный срок истекает раньше, он сохраняется: перевыпуск не продлевает ключ и не возвращает к жизни истёкший.

Заблокированный ключ тоже перевыпускается. Перевыпуск — единственный способ заменить ключ в статусе BLOCKED, разблокировки нет. Блокировка прежнего ключа остаётся, переходного периода он не получает, а его токены доступа гасятся, а не переезжают на новый ключ.

Ответ 500 — новый ключ создан, но замена отменена. Значения нового ключа в ответе нет. Его идентификатор приходит в error.details.orphanKeyId. Поле error.details.strandedSlots появляется, если при отмене что-то не удалось вернуть прежнему ключу, и перечисляет это: applications, servers, accessTokens, deployOperations, bots, previousKeyGrace. Если поля нет или в нём нет previousKeyGrace, прежний ключ сохраняет прежний срок действия. Дальнейшие шаги:

• Поле strandedSlots есть — обратитесь в поддержку. Не удаляйте новый ключ, пока на него что-то ссылается.
• Поля strandedSlots нет — удалите новый ключ запросом DELETE /v1/keys/:id с идентификатором из orphanKeyId. После ответа 204 ещё раз перевыпустите прежний ключ. Если удаление ответило 409 KEY_ROTATION_RECOVERY_REQUIRED, обратитесь в поддержку.

Пока замена не завершена, перевыпуск и удаление прежнего и нового ключа отвечают 409 KEY_ROTATION_RECOVERY_REQUIRED, поэтому повтор перевыпуска без этих шагов не пройдёт. Исключение — удаление нового ключа по второму пункту.

Отказ по ключу, выданному платформой, прежний ключ не трогает. При отказе SYSTEM_KEY_ROTATE_FORBIDDEN или отказе по подписке Cowork/Code прежний ключ продолжает работать. Обычных ключей кабинета эти проверки не касаются. Что умеет ключ подписки — Свой агент на подписке.

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

• Список API-ключей портала
• Создать API-ключ
• Получить API-ключ
• Изменить API-ключ
• Удалить API-ключ
• Менеджмент-ключи