Документация1С-Битрикс: Модулиnative.apiНастройки модуля

Безопасность

Вкладка «Безопасность» находится в разделе «Сервисы → API-платформа → Настройки модуля». Она задаёт сроки действия токенов и ограничения для входящих API-запросов.

Токены авторизации

Срок access-токена

Время действия токена доступа в секундах. Пустое поле использует значение по умолчанию — 10800 секунд, или 3 часа.

Срок refresh-токена

Время действия токена обновления в секундах. Пустое поле использует значение по умолчанию — 2592000 секунд, или 30 дней. Оно не может быть меньше срока жизни access-токена.

Для обоих полей допустимо целое число от 1 до 3153600000 секунд. Ноль не допускается. Срок отсчитывается от выпуска токена. Изменение настройки применяется к новым парам, в том числе при обновлении; сроки уже выпущенных токенов не пересчитываются.

Выпуск, обновление и отзыв отдельных клиентов описываются в разделе «Токены авторизации».

Ключ шифрования

Так поле называется в интерфейсе. Ключ используется для хеширования токенов перед хранением в базе.

Кнопка «Сгенерировать ключ» после подтверждения немедленно делает недействительными все ранее выпущенные access- и refresh-токены всех клиентов. Для продолжения работы клиентам потребуется получить новые пары токенов. Генерация требует права изменения настроек.

Расписание

Дни и время

В строке «Все пользователи» задайте общее расписание: отметьте разрешённые дни недели и заполните «начало» и «окончание» в формате ЧЧ:ММ. Используется время сервера, на котором выполняется PHP.

По умолчанию доступ разрешён каждый день круглосуточно.
Для круглосуточной работы в выбранные дни укажите 00:00 в обоих полях.
Одинаковые начало и окончание означают отсутствие ограничения по времени внутри выбранных дней.
Окончание не может быть раньше начала; интервал через полночь одной строкой не задаётся.
Если дни не выбраны, эта строка не разрешает доступ ни в один день.

Расписания групп

Расписания групп дополняют общий режим. Для допуска достаточно одного подходящего правила:

Текущие день и время сервера
├─ Подходят общему расписанию → доступ по времени разрешён
└─ Не подходят
   ├─ Подходят расписанию группы → доступ по времени разрешён
   └─ Не подходят ни одному → HTTP 403

Например, общий режим можно ограничить буднями с 09:00 до 18:00, а отдельной группе разрешить круглосуточный доступ во все дни. При общем круглосуточном доступе более узкое расписание группы его не ограничит.

Лимиты запросов

Количество и период

В поле «количество» задайте число запросов, а в поле «секунды» — период их учёта. Например, 100 и 60 задают ограничение в 100 запросов за последние 60 секунд.

Значение	Поведение
«количество» пустое или равно `0`	Правило отключено
«секунды» пустое	Правило отключено
«секунды» равно `0`, количество больше `0`	Учитывается вся сохранённая история без ограничения по времени

Запросы авторизованного пользователя учитываются совместно для его клиентов и IP-адресов. Для запросов без авторизации учёт ведётся по IP-адресу. История доступна в разделе «Входящие запросы»; для расчёта учитываются только записи со статусом «Обработан». Отказы лимитера и запросы, завершённые до проверки лимита, включая OPTIONS, в подсчёт не входят. Удаление обработанных записей влияет на расчёт лимитов.

При превышении возвращается HTTP 429. Для периода больше нуля заголовок Retry-After указывает, через сколько секунд можно повторить запрос. При одновременных запросах возможно превышение настроенного порога.

Лимиты групп

Есть активные лимиты групп пользователя?
├─ Нет → правило «Все пользователи»
└─ Да → только подходящие групповые правила
         ├─ Количество → максимум из правил
         └─ Период → максимум из правил

Количество и период выбираются независимо: итог может объединять значения разных групп.

Например, правила 100 за 120 секунд и 200 за 60 секунд дадут 200 за 120 секунд. Отключённое правило группы не отменяет общий лимит.

Расписания и групповые лимиты используют пользователя, определённого авторизацией API. Открытая административная сессия сама по себе не подменяет эту авторизацию.

CORS

CORS настраивает обращения к API из JavaScript на другом сайте. Эти настройки не заменяют авторизацию: запрос без заголовка Origin не проверяется по списку источников.

Кеширование CORS

Срок, на который браузер может запомнить результат предварительного запроса OPTIONS. Пустое поле использует 3600 секунд; 0 отключает кеширование этой проверки. Браузер может ограничить фактический срок. На кеширование ответов роутов поле не влияет.

Разрешённые Origin

Укажите по одному источнику на строку: протокол, домен и при необходимости порт, без пути страницы. Поддерживаются точные адреса и шаблоны поддоменов:

https://app.example.com
https://*.example.org

Шаблон во второй строке разрешает, например, https://shop.example.org, но не сам https://example.org. Значение * разрешает любой источник и указывается отдельно от других значений. Пустое поле также использует * — оно не запрещает обращения с других сайтов. Запрос с запрещённым Origin отклоняется с HTTP 403.

Разрешённые заголовки

Дополнительные заголовки, которые браузер может передавать в запросе, — по одному на строку. Например, X-Client-Version.

Origin, Content-Type, Authorization и X-Requested-With разрешены всегда. Пустое поле оставляет этот базовый набор; пользовательские значения дополняют его.

Заголовки ответа

Заголовки ответа, которые JavaScript на другом сайте сможет прочитать, — по одному на строку. Например, X-Total-Count. Заголовок Retry-After доступен всегда. Поле не создаёт заголовок: он должен присутствовать в ответе API.

Ограничения по IP

Эти списки действуют на весь API и проверяются до выбора роута, в том числе для OPTIONS. Дополнительные IP-ограничения конкретного роута задаются в его карте. Запрос должен пройти оба уровня.

Указывайте по одному IPv4-, IPv6-адресу или подсети CIDR на строку. Например:

192.0.2.10
198.51.100.0/24
2001:db8::/32

Чёрный список IP

Запрещает запросы с перечисленных адресов и подсетей. Проверяется первым; совпадение запрещает доступ даже при наличии адреса в белом списке.

Белый список IP

Если заполнен, разрешает запросы только с перечисленных адресов и подсетей. Пустой список не вводит дополнительных ограничений. При двух пустых глобальных списках остаются только IP-ограничения, заданные в карте выбранного роута.

Проверяется адрес из REMOTE_ADDR. Заголовки X-Forwarded-For и Forwarded не учитываются. Если сайт работает за прокси, учитывайте адрес, который веб-сервер передаёт PHP. Запрет по IP возвращает HTTP 403.