Срок действия токена, проверка и завершение сессии

Токен позволяет внешней программе работать с API в рамках сессии сотрудника. Сервер проверяет её при авторизованных запросах, может изменять срок и отзывает токен при выходе. Здесь показано, как проверить сессию, обработать отказ и завершить нужное подключение.

Одна сессия и её токен

После входа через auth/gettoken программа получает строку token.auth. Передавайте её целиком в заголовке auth следующих запросов, без префикса Bearer. Получение токена описано в статье «Авторизация по логину и паролю».

Используйте выданный токен повторно в рамках сессии. Каждый успешный вход создаёт новую сессию, поэтому получать токен перед каждым рабочим запросом не нужно.

Начальный срок и его изменение

Поле token.lifetime в ответе входа показывает первоначальное окончание срока по времени сервера. При последующих запросах эта дата может измениться:

Новая дата может оказаться раньше прежней. Например, токен выдан 9 ноября 2026 года до 9 января 2027 года. При проверке 26 ноября осталось 44 суток. Сервер установит окончание на 26 декабря, на 14 дней раньше первоначальной даты. Месяц здесь календарный, он не равен фиксированным 30 суткам.

Эти правила применяются при успешной проверке сессии как в auth/check, так и в обычных авторизованных запросах. Отдельного refresh-token запроса для этого сценария нет. Активная работа не защищает от отзыва токена или блокировки сотрудника.

Когда и как проверять сессию

Используйте auth/check, когда интеграция запускается с сохранённым токеном, восстанавливает подключение или выясняет причину отказа. Вызывать его перед каждой операцией не обязательно: рабочие методы сами проверяют авторизацию.

В примерах адрес и сведения сотрудника условные. Подставьте свой сервер и сохранённую строку token.auth вместо YOUR_AUTH_TOKEN:

curl 'https://lab.example/api/auth/check' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json'

Запрос выполняется методом GET. При действующей сессии сервер возвращает HTTP 200 и сведения сотрудника. Фрагмент ответа:

{
  "id": 900301,
  "department": 900501,
  "login": "integration-demo",
  "adm": 0,
  "name": "Иван",
  "fname": "Примеров",
  "oname": "Иванович",
  "internum": 101
}

Сопоставьте id и login с ожидаемым сотрудником. Они находятся в корне JSON, без обёртки user или res. Нового lifetime этот ответ не содержит.

Проверка обращается к серверу и сама может изменить срок сессии. Её успех подтверждает состояние на момент запроса. Следующий метод проверяет сессию и доступ к своей операции заново, поэтому его ответ тоже нужно обработать.

Завершение нужной сессии

Чтобы отозвать токен, отправьте POST с этим же значением auth:

curl 'https://lab.example/api/system/logout' \
  -X POST \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json'

При успешном выполнении сервер помечает токен закрытым и устанавливает окончание его срока. Ответ HTTP 200 может содержать пустой JSON-массив:

[]

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

Сессия определяется токеном, а не вкладкой или устройством. Несколько вкладок с одним token.auth используют одну сессию: отзыв общего токена касается их всех. Другие токены того же сотрудника этот запрос не закрывает. Штатный клиент сопоставляет уведомление о выходе со своей сессией.

Удаление токена из памяти внешней программы само по себе не отзывает его на сервере. Для подтверждения отзыва нужен успешный ответ system/logout. Если ответ потерян, результат запроса неизвестен. Уже истёкший или закрытый токен может получить отказ авторизации до выполнения команды выхода.

Коды отказов

Если auth/check завершился отказом, учитывайте HTTP-статус и поля title, mess ответа. Поле mess может быть пустым.

У прикладного метода 403 также может означать отсутствие доступа к операции. В этом случае получение нового токена не заменяет нужный доступ. Не запускайте бесконечные повторы с токеном, который сервер отклоняет.

Если ответ на операцию потерян

Сетевой сбой не доказывает, что сессия истекла или операция не выполнена. Например, сервер мог создать заявку, но ответ не дошёл до интеграции. Позднейший отказ auth/check ничего не говорит об исходе того добавления.

1. Если для поиска результата нужен новый токен, выполните повторный вход.
2. Выясните, была ли первая операция выполнена.
3. Только после этого решайте, нужен ли повтор записи, с учётом правил повторных запросов и диагностики сбоев.

Хранение токена и повторный вход

Храните token.auth как секрет и не включайте его в журналы или адреса запросов. Сохранённый при входе lifetime помогает понять начальный срок, но не показывает последующие изменения на сервере. Для проверки сохранённого токена внешняя программа может вызвать auth/check.

В приложении TesLab при перезапуске после первоначального срока может потребоваться повторный вход, даже если запросы ранее продлевали серверную сессию. Это ограничение восстановления сессии приложением. Локальный выход очищает учётные данные и отправляет запрос на сервер, не дожидаясь подтверждения отзыва; при отсутствии связи подтвердить серверный отзыв таким выходом нельзя.

Связанные материалы

• API TesLab: адрес сервера и первый запрос.
• HTTP Basic для серверных интеграций: отдельный сценарий подключения, в том числе для обмена с 1С.