API-токены

API-токен (Personal Access Token, PAT) — ключ для программного доступа к API Tracehub: прежде всего к Pull API и файловым выгрузкам (см. страницу Экспорт данных). Токен принадлежит вам как пользователю и действует в тех организациях, к которым вы его привязали.

Разделы управления токенами

Токены доступны в двух местах кабинета — список общий:

• Настройки → API-токены — полная поверхность: создание с выбором организаций и любых доступных прав, переименование, перевыпуск, отзыв;
• Данные → Экспорт → вкладка «API-ключи» — упрощённое создание под Pull API: права export:read (выгрузка данных) и report:read (отчёты), привязка к приложениям текущей организации.

Создание

Поле	Описание
Название	Как вы узнаете ключ в списке, например «Выгрузка в BI»
Описание	Необязательная заметка, где используется
Организации	К каким организациям привязан токен. Права одинаковы во всех выбранных
Права (scopes)	Что токену разрешено. Не могут быть шире вашей собственной роли; при нескольких организациях — не шире пересечения ролей в них
Приложения	Все приложения организации (включая созданные позже) или явный список
Срок действия	Предустановленные сроки — 30, 90 или 365 дней — либо «Без срока». Явный срок длиннее года укорачивается до 365 дней (актуально при создании через API)

Для Pull API токену достаточно права export:read.

Секрет токена — строка вида tracehub_pat_… — показывается один раз, сразу после создания. Сохраните его в менеджере секретов: повторно получить секрет нельзя, только перевыпустить. В списках токен опознаётся по первым символам (префиксу) и полю «Последнее использование» — дате последнего запроса.

Бессрочный ключ — постоянный риск при утечке

Выбирайте срок действия; по его истечении создайте новый токен. Не коммитьте секрет в репозиторий и не передавайте в URL.

Перевыпуск и отзыв

• Перевыпустить — выпускается новый секрет; старый продолжает работать ещё 5 минут (grace-период), чтобы вы успели обновить его в интеграциях без простоя. Через API grace-период настраивается от 0 до 3600 секунд.
• Отозвать — токен перестаёт работать немедленно; все клиенты с этим ключом теряют доступ.

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

Лимиты

Ограничение	Значение
Активных токенов на пользователя	10
Запросов на токен	100 в час (по умолчанию)
Явный срок действия	максимум 365 дней (токен «Без срока» возможен)

---