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

`POST /v1/connect/revoke`

Эндпоинт сделан по RFC 7009 и отзывает **один** ключ — тот, который вы в нём предъявили. Вызывайте его, когда пользователь выключил интеграцию у вас на стороне: иначе прежние ключи остаются рабочими и занимают места в [лимите ключей](/docs/partner-connect/keys#лимит-ключей).

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

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

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

## Примеры

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

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

```bash
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` | Условие |
|------|---------|---------|
| 400 | `invalid_request` | Не передан `client_id` или `token` |
| 400 | `invalid_client` | Публичный клиент передал `client_secret` |
| 401 | `invalid_client` | Клиент неизвестен или секрет не подошёл |
| 409 | `key_manages_foreign_server` | Ключ управляет живым сервером другого владельца, сервером без владельца или сервером того же владельца на другом портале. Поле `code` — `KEY_MANAGES_FOREIGN_SERVER`. Установите владельца и нужный портал сервера, перепривяжите его к ключу этого владельца в том же портале и затем повторите отзыв |
| 409 | `key_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 — [Ошибки](/docs/errors).

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

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

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

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

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

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

- [Время жизни, отзыв и лимит ключей](/docs/partner-connect/keys)
- [Обменять код на API-ключ](/docs/partner-connect/token)
- [Partner Connect](/docs/partner-connect)
