OAuth 2.0 авторизация в Битрикс24

OAuth 2.0 — стандартный протокол авторизации приложений Битрикс24: вместо секретного URL приложение получает access_token и refresh_token. Разберём полный цикл — от кода авторизации до автоматического обновления токена, с примерами запросов и обработкой ошибок.

Зачем OAuth, если есть вебхук

Вебхук отдаёт секретный код навсегда и работает от имени одного пользователя. OAuth решает другие задачи:

• Действия от имени установившего — каждый пользователь авторизуется сам, приложение действует в его правах.
• Ограниченный срок токена — access_token живёт ~1 час, утечка менее критична.
• Работа на многих порталах — один и тот же client_id обслуживает разные компании.
• Отзыв доступа — пользователь удаляет приложение, и токены перестают работать.

Именно поэтому все приложения — и локальные, и тиражные из Маркетплейса — авторизуются через OAuth 2.0, а не через секрет в URL.

Компоненты авторизации

Для OAuth-обмена участвуют несколько сущностей:

Сервер авторизации Битрикс24 — oauth.bitrix.info. Через него проходит выдача и обновление токенов, независимо от домена конкретного портала.

Шаг 1. Получение кода авторизации

Приложение перенаправляет пользователя на страницу авторизации портала. Пользователь подтверждает права, и портал возвращает code на ваш redirect_uri.

GET https://mycompany.bitrix24.ru/oauth/authorize/
    ?client_id=local.xxxxxxxx
    &response_type=code
    &redirect_uri=https://myapp.example.com/oauth/callback

// Редирект обратно с кодом:
https://myapp.example.com/oauth/callback?code=abc123def456

Для локальных приложений код нередко приходит сразу при установке — тогда шаг с редиректом можно пропустить и переходить к обмену на токены. Код одноразовый и быстро истекает, обменять его нужно немедленно.

Шаг 2. Обмен кода на токены

Ваш backend меняет code на пару токенов, обращаясь к серверу авторизации с client_secret:

GET https://oauth.bitrix.info/oauth/token/
    ?grant_type=authorization_code
    &client_id=local.xxxxxxxx
    &client_secret=SECRET
    &code=abc123def456

// Ответ
{
  "access_token": "a1b2c3...",
  "refresh_token": "r9r8r7...",
  "expires_in": 3600,
  "scope": "crm,user,task",
  "domain": "oauth.bitrix.info",
  "member_id": "a223c...",
  "client_endpoint": "https://mycompany.bitrix24.ru/rest/"
}

Сохраните оба токена и client_endpoint — именно к нему вы будете обращаться при вызовах API, добавляя auth=access_token.

Шаг 3. Вызов метода с токеном

Теперь можно вызывать любой метод в рамках выданного scope, передавая access_token:

POST https://mycompany.bitrix24.ru/rest/crm.deal.list.json
{
  "auth": "a1b2c3...",
  "filter": { ">OPPORTUNITY": 10000 },
  "select": ["ID", "TITLE", "OPPORTUNITY"]
}

Если токен истёк, придёт ошибка expired_token или invalid_token. Это не повод заново гонять пользователя через авторизацию — достаточно обновить токен.

Шаг 4. Обновление токена

По refresh_token получают свежую пару токенов без участия пользователя:

GET https://oauth.bitrix.info/oauth/token/
    ?grant_type=refresh_token
    &client_id=local.xxxxxxxx
    &client_secret=SECRET
    &refresh_token=r9r8r7...

// Ответ содержит новые access_token и refresh_token

Практично обновлять токен реактивно — по факту ошибки, а не по таймеру: так вы не зависите от рассинхронизации часов и не тратите обновления впустую.

Итог

OAuth 2.0 в Битрикс24 — это четыре шага: получить код авторизации, обменять его на access_token и refresh_token, вызывать методы с токеном и обновлять его по refresh_token. Ключевые правила: хранить client_secret только на сервере, сохранять обе части обновлённой пары токенов и обрабатывать invalid_token повтором с обновлением. Это фундамент любого приложения — локального или из Маркетплейса.

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