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

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

В разделе «Сервисы → API-платформа → Токены авторизации» можно просматривать, создавать, изменять и отзывать токены. Для просмотра нужно право чтения, для остальных действий — также право изменения на вкладке «Доступ».

Пары токенов и клиенты

Назначение токенов

При выпуске создаётся пара:

access — для обращения к роутам с токен-авторизацией;
refresh — для получения новой пары после истечения или до окончания срока access-токена.

Сроки задаются на вкладке «Безопасность». При ротации выпускаются оба новых токена, прежняя пара отзывается. Если refresh-токен тоже истёк, нужно заново получить пару с авторизацией по логину и паролю.

Выпуск пары: POST /token с Basic
│
├─ access → запросы к защищённым роутам
│
└─ refresh → PUT /token с Bearer
             │
             └─ Новая пара access + refresh
                Прежняя пара отозвана

После выпуска и каждого обновления сохраняйте оба токена. Для отзыва клиентской сессии используйте DELETE /token с access-токеном и client_id этой сессии. Требования MFA и параметры операций приведены ниже.

Значения токенов показываются только при выпуске. Восстановить их из административного списка нельзя.

Несколько клиентов

У одного пользователя может быть несколько клиентских сессий — например, для браузера и мобильного приложения. При штатном выпуске через API клиент определяется по заголовкам запроса. Повторная выдача для того же пользователя и клиента заменяет его прежние токены; сессии других клиентов сохраняются.

Access- и refresh-токены, выпущенные через API, проверяют привязку к клиенту при каждом использовании. При несовпадении возвращается AUTH_INVALID (HTTP 401). Сохраняйте одинаковые заголовки клиента при выпуске, обновлении и вызове защищённых роутов. Состав заголовков и исключение для ручных токенов.

Работа через API

Для встроенных операций включите нативные роуты. В таблице пути указаны относительно адреса API.

Метод	Путь	Авторизация	Назначение
POST	/token	Basic	Выпустить пару для текущего клиента
GET	/token	Basic	Получить список активных токен-сессий пользователя
PUT	/token	Bearer с refresh-токеном	Заменить прежнюю пару новой
DELETE	/token	Bearer с access-токеном	Отозвать токены клиента, указанного в параметре `client_id`

Откройте эти операции во встроенной документации: там приведены параметры, примеры ответов и порядок выполнения запросов. Для удаления берите client_id из списка сессий. Можно завершить свою сессию или сессию другого клиента этого же пользователя.

Если при выпуске получена ошибка AUTH_MFA_REQUIRED, пройдите многофакторную авторизацию на штатной форме сайта и повторите запрос с логином, паролем и cookie подтверждённой сессии того же пользователя.

Административный список

Поля и поиск

Каждая строка соответствует одному токену. Одна пара представлена двумя записями. Список содержит и истёкшие токены, пока их записи не удалены.

Поле	Назначение
Пользователь	Владелец токена
Дата создания и Дата окончания	Время выпуска и срок действия конкретного токена
Тип токена	`access` или `refresh`
ID клиента, Название клиента, Тип клиента	Сведения о клиентской сессии
Агент	Сведения User-Agent
IP-адрес	Адрес, сохранённый при выпуске токена
Хеш токена	Хешированное значение; для авторизации не используется
ID связанного токена	Ссылка на второй токен пары

Используйте фильтры по пользователю, датам и типу токена, а строку поиска — по названию клиента. Дополнительные столбцы можно включить в настройках списка. Нажатие на ID открывает карточку токена.

Ручной выпуск

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

Нажмите «Добавить токен».
Выберите пользователя и укажите будущую дату окончания access-токена.
Сохраните форму. Refresh-токен получит срок из настроек безопасности.
Сохраните показанные значения access- и refresh-токенов: после обновления или ухода со страницы они больше не отображаются.

Токены, выпущенные вручную, можно использовать в другом приложении. Они не привязаны к заголовкам клиента; срок действия и возможность отзыва сохраняются.

Ручной выпуск для пользователя с ID = 1 запрещён. Действие копирования в списке открывает форму выпуска для того же пользователя; оно создаёт новую пару, а не копирует секреты прежней.

Изменение и удаление

У существующей записи можно изменить «Дату окончания», «Название клиента» и «Агент». Изменение относится только к выбранной записи: срок второго токена пары автоматически не меняется. Это не ротация — значение токена остаётся прежним.

Действие «Удалить» отзывает выбранный токен вместе с парным. Поддерживается удаление выделенных записей и всех записей, соответствующих фильтру. Перед массовым удалением проверьте выборку.

Для отзыва доступа используйте удаление пары: сокращение срока только access-токена не запрещает получение новой пары по ещё действующему refresh-токену.

Журналирование

Запись операций включается на вкладке «Логирование». Просмотр доступен через «События токенов» и «События модуля» при наличии прав системного журнала.