Авторизация в API: вебхук или OAuth
Без авторизации REST API Битрикс24 не работает. Каждый запрос должен содержать данные, которые подтверждают: «этот запрос имеет право быть выполненным». Без них Битрикс24 отклонит запрос с ошибкой `NO_AUTH_FOUND`.
Есть два способа передать эти данные: входящий вебхук и OAuth 2.0. Вебхук — это постоянный секретный код в адресе запроса. OAuth — это временный токен, который приложение получает после авторизации пользователя и обновляет автоматически. Выбор зависит от задачи: вебхук для быстрой интеграции с одним порталом, OAuth для приложения, которое работает от имени разных пользователей.
В этой статье — как работает авторизация, чем отличаются способы, как настроить и не потерять доступ. Если нужна разработка интеграции через API — поможем.
Содержание статьи
Вебхук
Входящий вебхук — это URL, в котором уже содержатся идентификатор пользователя и секретный код. Запрос к этому URL выполняется от имени создателя вебхука и в рамках выбранных `scope`.
Как выглядит
https://your-domain.bitrix24.com/rest/1/xxxxxxxx/crm.item.add.json
Где `/1` — ID пользователя, `xxxxxxxx` — секретный код, `crm.item.add` — метод.
Когда использовать
- Простая интеграция — форма на сайте создаёт лид;
- Разовый импорт или экспорт — перенос данных;
- Скрипты — массовое обновление;
- Тесты — проверить метод в браузере или `curl`.
Ограничения
Часть методов через вебхук недоступна: встраивание виджетов (`placement.bind`), часть методов телефонии, некоторые сценарии чат-ботов. Они требуют контекста приложения и вернут ошибку `WRONG_AUTH_TYPE`.
💡 Важно
Секретный код вебхука — это пароль. Не публикуйте его, не передавайте в клиентский код, не храните в публичных репозиториях. При компрометации код блокируется, генерируется новый.
OAuth 2.0
OAuth 2.0 — это полный протокол авторизации. Приложение не хранит логин и пароль пользователя, а получает временный токен, который можно отозвать или обновить .
Когда нужен
- Приложение работает вне интерфейса Битрикс24 — свой веб-сервис, отдельное ПО;
- Работа от имени разных пользователей — тиражное приложение;
- Нужно управление доступом — токен можно отозвать .
Как работает
Пять шагов :
- Пользователь сообщает адрес своего Битрикс24;
- Приложение перенаправляет пользователя в его Битрикс24 с `client_id`;
- Пользователь авторизуется и возвращается с одноразовым кодом `code` (живёт 30 секунд);
- Приложение обменивает `code`, `client_id` и `client_secret` на токены;
- Сервер возвращает `access_token` и `refresh_token`.
Что важно
`client_secret` используется только в запросах к серверу авторизации `oauth.bitrix.info`. Нельзя размещать его в браузерном коде, репозиториях, логах.
Что выбрать
| Параметр | Вебхук | OAuth 2.0 |
|---|---|---|
| Сложность | Низкая | Высокая |
| Для чего | Один портал, простая интеграция | Приложение, разные пользователи |
| Срок действия | Постоянный (пока не отозван) | `access_token` — 1 час, `refresh_token` — 180 дней |
| Права | Права создателя вебхука | Права авторизованного пользователя |
| Методы | Не все (без контекста приложения) | Все, доступные приложению |
Простое правило: если интеграция работает с одним порталом и не требует сложной логики — вебхук. Если это приложение для разных компаний или нужен контроль доступа — OAuth.
Сроки жизни токенов
В OAuth 2.0 два токена, и у каждого свой срок.
| Токен | Срок | Что делать |
|---|---|---|
| access_token | 1 час | Использовать для запросов, обновлять при истечении |
| refresh_token | 180 дней | Хранить, обменивать на новую пару |
| code | 30 секунд | Обменять на токены сразу после получения |
Если приложение не обращается к Битрикс24 больше 180 дней, `refresh_token` истекает, и пользователю придётся авторизоваться заново.
Продление
Приложение хранит `refresh_token` и обменивает его на новую пару токенов без участия пользователя. Запрос отправляется на сервер авторизации.
Как выглядит запрос
GET https://oauth.bitrix.info/oauth/token/
?grant_type=refresh_token&client_id=...&client_secret=...&refresh_token=...
Что возвращается
- access_token — новый токен доступа;
- refresh_token — новый токен обновления (сохранить вместо старого);
- expires — момент истечения;
- expires_in — срок жизни в секундах.
💡 Важно
Не продлевайте токены по расписанию «на всякий случай». Обновляйте при истечении или по ошибке `expired_token`. Это снижает нагрузку и риск ошибок.
Права пользователя
И вебхук, и OAuth выполняются от имени конкретного пользователя. API не обходит права доступа: если сотрудник не видит сделку в интерфейсе, метод не вернёт её и через API.
Как это работает
- Вебхук — права создателя. Если создатель уволен, доступ может потеряться;
- OAuth — права пользователя, который авторизовался;
- Scope — дополнительное ограничение: даже с правами пользователя метод не выполнится, если scope не выдан.
Это защита, а не ограничение. Если бы API мог обходить права, это была бы дыра в безопасности.
Ошибки
1. NO_AUTH_FOUND
Не переданы данные авторизации. Проверьте URL вебхука или параметр `auth`.
2. INVALID_CREDENTIALS
Вебхук заблокирован или код неверен. Сгенерируйте новый код в настройках.
3. expired_token
`access_token` истёк. Обменяйте `refresh_token` на новую пару.
4. insufficient_scope
Не выдан нужный scope. Добавьте его в настройках вебхука или приложения.
5. WRONG_AUTH_TYPE
Метод требует контекста приложения. Через вебхук недоступен.
6. Утечка секретов
`client_secret` или код вебхука в публичном доступе. При компрометации — блокировка и генерация нового.
Наши рекомендации
Что вы получаете, заказывая настройку авторизации у нас
- Выбор способа — вебхук или OAuth
- Настройку вебхука — scope, права, безопасность
- Настройку OAuth — токены, продление, хранение
- Проверку прав — что вернёт API
- Документацию — для команды
📌 Итоговый вывод
Авторизация — это не «формальность», а способ защитить данные и не потерять доступ.
Что нужно знать:
- Вебхук: постоянный код в URL, для одного портала, простая интеграция;
- OAuth 2.0: временные токены, для приложений, работа от имени разных пользователей ;
- Сроки: `access_token` — 1 час, `refresh_token` — 180 дней, `code` — 30 секунд;
- Продление: обмен `refresh_token` на новую пару через `oauth.bitrix.info`;
- Права: API не обходит права пользователя;
- Ошибки: `NO_AUTH_FOUND`, `expired_token`, `insufficient_scope`, `WRONG_AUTH_TYPE`.
Также рекомендуем: API, методы REST API, вебхуки, все статьи об API.