Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/revoke.md индекс документации — /llms.txt

Отозвать ключ приложением

POST /v1/connect/revoke

Эндпоинт сделан по RFC 7009 и отзывает один ключ — тот, который вы в нём предъявили. Вызывайте его, когда пользователь выключил интеграцию у вас на стороне: иначе прежние ключи остаются рабочими и занимают места в лимите ключей.

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

Принимается application/x-www-form-urlencoded и JSON с теми же полями.

Поле Тип Обяз. Описание
Полеclient_id Типstring Обяз.да ОписаниеИдентификатор приложения
Полеclient_secret Типstring Обяз.условно ОписаниеСекрет приложения. Конфиденциальные клиенты передают обязательно. Публичные клиенты (PUBLIC) не передают — его у них нет
Полеtoken Типstring Обяз.да ОписаниеAPI-ключ, который нужно отозвать. Ключ приходит в поле api_key ответа POST /v1/connect/token

Примеры

Эндпоинт авторизуется учётными данными приложения — client_id и client_secret в теле запроса. Заголовки X-Api-Key и Authorization не нужны.

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

Terminal
curl -X POST https://vibecode.bitrix24.tech/v1/connect/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d token=API_KEY_TO_REVOKE

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/connect/revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    token: apiKeyToRevoke,
  }),
})

if (res.status === 200) {
  // ключ отозван либо отзывать было нечего — повтор безопасен
}

Поля ответа

Успешный ответ — HTTP 200 с пустым объектом {}. Один и тот же ответ приходит на неизвестный токен, на чужой ключ и на уже отозванный — так перебором нельзя выяснить, живы ли чужие ключи. Значит, вызов идемпотентен: повторить его безопасно.

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

JSON
{}

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

401 — клиент неизвестен:

JSON
{
  "error": "invalid_client",
  "error_description": "Unknown client"
}

Ошибки

Ошибки приходят в форме RFC 7009 — { error, error_description }, без обёртки success. Исключение — отказ ограничителя частоты, его форма описана после таблицы.

HTTP error Условие
HTTP400 errorinvalid_request УсловиеНе передан client_id или token
HTTP400 errorinvalid_client УсловиеПубличный клиент передал client_secret
HTTP401 errorinvalid_client УсловиеКлиент неизвестен или секрет не подошёл
HTTP409 errorkey_manages_foreign_server УсловиеКлюч управляет живым сервером другого владельца, сервером без владельца или сервером того же владельца на другом портале. Поле code — KEY_MANAGES_FOREIGN_SERVER. Установите владельца и нужный портал сервера, перепривяжите его к ключу этого владельца в том же портале и затем повторите отзыв
HTTP409 errorkey_operation_in_progress УсловиеТот же ключ сейчас меняет другая операция. Поле code — KEY_OPERATION_IN_PROGRESS. Повторите запрос после её завершения

Тело обоих отказов 409 содержит error, error_description и code.

Ограничителей частоты здесь два, и оба отвечают 429. Собственный ограничитель эндпоинта: 60 запросов в минуту. Действующее значение — в заголовке x-ratelimit-limit. Считается только по адресу вызывающего — client_id в ключ не входит намеренно, поэтому его ротация нового бюджета не даёт, а все копии интеграции за одним адресом делят эти 60. Заголовки X-RateLimit-* он ставит. Ограничитель на входе в платформу: 60 запросов в секунду на адрес, и этот счётчик общий на весь /v1/, а не на этот эндпоинт. Заголовков X-RateLimit-* он не ставит, а Retry-After у него всегда 1. Тело в обоих случаях приходит в общем конверте API — { "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }, — то есть отличается от формы RFC 7009 остальных ответов этого эндпоинта, и различить ограничители по телу нельзя, только по наличию X-RateLimit-Limit. Вызов не терминальный: ключ не отозван, повторите после паузы из Retry-After.

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

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

Отзыв прекращает работу ключа сразу. Если предъявленный ключ выпущен именно вашему клиенту и был активен, после отзыва запросы с ним отвечают 401 KEY_INACTIVE, а место в лимите освобождается. Сам по себе ответ 200 {} не доказывает отзыв: неизвестный, чужой клиенту и уже отозванный ключ дают тот же ответ.

Деактивация клиента отзыву не мешает. Отозвать можно и ключ, выданный до деактивации вашего клиента: деактивация закрывает выдачу новых ключей, но отзыв прежних не запрещает.

Чего эндпоинт не делает:

  • не снимает вебхук на портале Битрикс24 — его пользователь удаляет у себя, отзыв ключа этого не заменяет.
  • не возвращает потерянный ключ — чтобы отозвать ключ, его надо предъявить, восстановить его нельзя.
  • не срабатывает сам — если пользователь перестал пользоваться интеграцией, ключ живёт дальше. Вызов эндпоинта — ваша ответственность.

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