Для 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-приложение
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-приложение
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 с пустым объектом {}. Один и тот же ответ приходит на неизвестный токен, на чужой ключ и на уже отозванный — так перебором нельзя выяснить, живы ли чужие ключи. Значит, вызов идемпотентен: повторить его безопасно.
Пример ответа
{}
Пример ответа при ошибке
401 — клиент неизвестен:
{
"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 — его пользователь удаляет у себя, отзыв ключа этого не заменяет.
- не возвращает потерянный ключ — чтобы отозвать ключ, его надо предъявить, восстановить его нельзя.
- не срабатывает сам — если пользователь перестал пользоваться интеграцией, ключ живёт дальше. Вызов эндпоинта — ваша ответственность.