Класс B24OAuth - Bitrix24 JS SDK

Объект B24OAuth предназначен исключительно для использования на сервере.

clientSecret, access token и refresh token никогда не должны попадать в код браузера.
Предупреждение о клиентской стороне по умолчанию включено на обоих HTTP-клиентах; см. offClientSideWarning.
Для клиентских сценариев используйте B24Frame.

Обзор

B24OAuth — это точка входа SDK для локальных приложений OAuth 2.0. Он принимает существующую пару токенов (выданную Bitrix24 при установке), использует access token для REST-вызовов и обновляет пару через oauth.bitrix.info, когда access token истекает.

Класс наследуется от AbstractB24 и реализует TypeB24, поэтому полный набор REST-методов (actions.v2.*, actions.v3.*, tools.*) доступен сразу после создания экземпляра — шаг await b24.init() не требуется.

Создание экземпляра B24OAuth

import { B24OAuth, EnumAppStatus } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth(
  // 1) Данные токена, полученные от Bitrix24 (payload события, OAuth-рукопожатие и т.д.)
  {
    applicationToken: '<your_application_token>',
    userId: 1,
    memberId: '<your_member_id>',
    accessToken: '<your_access_token>',
    refreshToken: '<your_refresh_token>',
    expires: 1745997853,        // unix-таймстамп, секунды
    expiresIn: 3600,            // секунды
    scope: 'crm,catalog,user_brief',
    domain: 'your_domain.bitrix24.com',
    clientEndpoint: 'https://your_domain.bitrix24.com/rest/',
    serverEndpoint: 'https://oauth.bitrix.info/rest/',
    status: EnumAppStatus.Free
  },
  // 2) Учётные данные приложения, выданные в Bitrix24 → Разработчикам → Приложения
  {
    clientId: 'local.xxxxxx.xxxxxx',
    clientSecret: '<your_client_secret>'
  }
)

const response = await $b24.actions.v2.call.make({
  method: 'tasks.task.list',
  params: { select: ['ID', 'TITLE', 'STATUS'] },
  requestId: 'tasks-list'
})

Сигнатура конструктора

constructor(
  authOptions: B24OAuthParams,
  oAuthSecret: B24OAuthSecret,
  options?: { restrictionParams?: Partial<RestrictionParams> }
)

Поля `B24OAuthParams`

Поле	Тип	Описание
`applicationToken`	`string`	Application token, выданный при установке.
`userId`	`number`	Идентификатор пользователя, которому принадлежит токен.
`memberId`	`string`	member id портала.
`accessToken`	`string`	Текущий access token.
`refreshToken`	`string`	Refresh token, используемый `refreshAuth`.
`expires`	`number`	Срок действия access token (unix-таймстамп, секунды).
`expiresIn`	`number`	Время жизни токена, секунды.
`scope`	`string`	Список scope через запятую (например, `crm,catalog,user_brief`).
`domain`	`string`	Домен портала (`xxx.bitrix24.com`).
`clientEndpoint`	`string`	Корень REST портала, например `https://xxx.bitrix24.com/rest/`.
`serverEndpoint`	`string`	OAuth-сервер, обычно `https://oauth.bitrix.info/rest/`.
`status`	`TypeEnumAppStatus`	Одно из `EnumAppStatus.Free / Demo / Trial / Paid / Local / Subscription`.

Поля `B24OAuthSecret`

Поле	Тип	Описание
`clientId`	`string`	OAuth `client_id` вашего приложения.
`clientSecret`	`string`	OAuth `client_secret` вашего приложения.

Процесс обновления токена

B24OAuth обновляет access token автоматически, когда:

REST-вызов возвращает expired_token, или
вызывается getAuthData() и expires <= Date.now().

Путь обновления по умолчанию вызывает GET /oauth/token/ на serverEndpoint (обычно https://oauth.bitrix.info/rest/) с grant_type=refresh_token, переданными refreshToken, clientId и clientSecret. При успехе менеджер обновляет accessToken, refreshToken, expires, expiresIn, clientEndpoint, serverEndpoint, scope и status.

Если запрос обновления завершается неудачей, SDK выбрасывает RefreshTokenError (подкласс SdkError), несущий code, description и HTTP-status.

Сохранение обновлённых токенов

Зарегистрируйте callback, чтобы ваше приложение могло сохранить новую пару токенов (БД, менеджер секретов и т.д.):

// @check-ignore: B24OAuth-specific method, ambient $b24 is typed as B24Frame

$b24.setCallbackRefreshAuth(async ({ authData, b24OAuthParams }) => {
  await tokenStore.save({
    accessToken: b24OAuthParams.accessToken,
    refreshToken: b24OAuthParams.refreshToken,
    expires: b24OAuthParams.expires,
    expiresIn: b24OAuthParams.expiresIn,
    memberId: authData.member_id
  })
})

Удаляется через $b24.removeCallbackRefreshAuth().

Кастомная логика обновления

Если ваше приложение получает refresh-токены из отдельного сервиса (например, централизованного брокера токенов), передайте функцию CustomRefreshAuth. SDK вызовет её вместо обращения к oauth.bitrix.info:

// @check-ignore: B24OAuth-specific method, ambient $b24 is typed as B24Frame

import type { HandlerRefreshAuth } from '@bitrix24/b24jssdk'

$b24.setCustomRefreshAuth(async (): Promise<HandlerRefreshAuth> => {
  const fresh = await tokenBroker.fetch()
  return {
    access_token: fresh.accessToken,
    refresh_token: fresh.refreshToken,
    expires: fresh.expires,
    expires_in: fresh.expiresIn,
    client_endpoint: fresh.clientEndpoint,
    server_endpoint: fresh.serverEndpoint,
    member_id: fresh.memberId,
    scope: fresh.scope,
    status: fresh.status,
    domain: fresh.domain
  }
})

Удаляется через $b24.removeCustomRefreshAuth().

Методы

`initIsAdmin`

initIsAdmin(requestId?: string): Promise<void>

Один раз вызывает REST-метод profile и кэширует, есть ли у аутентифицированного пользователя права администратора. Требуется перед чтением auth.isAdmin — геттер выбрасывает Error('isAdmin not init. You need call B24OAuth::initIsAdmin().') при слишком раннем вызове.

// @check-ignore: B24OAuth-specific method, ambient $b24 is typed as B24Frame

await $b24.initIsAdmin('boot:isAdmin')
if ($b24.auth.isAdmin) {
  // ...
}

`setCallbackRefreshAuth` / `removeCallbackRefreshAuth`

setCallbackRefreshAuth(cb: CallbackRefreshAuth): void
removeCallbackRefreshAuth(): void

Регистрирует / снимает callback, выполняемый после каждого успешного обновления. См. Сохранение обновлённых токенов.

`setCustomRefreshAuth` / `removeCustomRefreshAuth`

setCustomRefreshAuth(cb: CustomRefreshAuth): void
removeCustomRefreshAuth(): void

Регистрирует / снимает кастомную реализацию обновления. См. Кастомная логика обновления.

`offClientSideWarning`

offClientSideWarning(): void

Отключает runtime-предупреждение, возникающее при обнаружении B24OAuth в браузерном окружении. Используйте только когда вы проксируете OAuth-токены через серверную обёртку.

`getTargetOrigin` / `getTargetOriginWithPath`

getTargetOrigin(): string
getTargetOriginWithPath(): Map<ApiVersion, string>

Возвращают origin портала (например, https://xxx.bitrix24.com) и REST-endpoint-ы для каждой версии, выведенные из clientEndpoint.

`getHttpClient` / `setHttpClient` / `setRestrictionManagerParams` / `getLogger` / `setLogger` / `destroy`

Унаследованы от AbstractB24 — та же структура, что и у B24Hook и B24Frame. См.:

Лимитеры — setRestrictionManagerParams.
Логгер — getLogger / setLogger.

Геттеры

`auth`

Возвращает экземпляр AuthOAuthManager, который реализует AuthActions:

getAuthData() — возвращает текущий AuthData или false, если access token истёк (следующий REST-вызов вызовет автоматическое обновление).
refreshAuth() — ручное обновление; выбрасывает RefreshTokenError при неудаче.
getUniq(prefix: string) — возвращает <prefix>_<memberId>.
isAdmin — требует предварительного вызова initIsAdmin().

`isInit`

get isInit(): boolean

Всегда true сразу после создания экземпляра.

Обработка ошибок

// @check-ignore: top-level return in error-handling illustration

import { B24OAuth, RefreshTokenError } from '@bitrix24/b24jssdk'

try {
  const response = await $b24.actions.v3.call.make({
    method: 'tasks.task.get',
    params: { id: 1, select: ['id', 'title'] },
    requestId: 'task-get-1'
  })
  if (!response.isSuccess) {
    // Обработка ошибок уровня REST
    console.error(response.getErrorMessages())
  }
} catch (error) {
  if (error instanceof RefreshTokenError) {
    // Refresh token мёртв — переавторизуйте приложение
    console.error('OAuth refresh failed:', error.message)
    return
  }
  throw error
}

FAQ

B24Hook

Серверная точка входа для работы с REST API Bitrix24 через входящий вебхук (постоянный токен).