ВойтиПопробовать бесплатно
Разделы документации

API-токены

Как выпустить токен для внешнего доступа к API трекера, выбрать доступ и срок действия и отозвать токен.

API-токен — ключ, с которым внешний сервис обращается к API трекера без входа в панель. Токены находятся в Настройки → API, блок API-токены; как попасть в раздел — см. Как открыть настройки. Раздел видят владелец и администратор.

Создание токена

  1. Откройте Настройки → API.
  2. Нажмите + Токен. Откроется окно «Создать API-токен».
  3. Заполните Название, например имя интеграции. Длина — до 200 латинских символов или до 100 кириллических.
  4. Выберите Доступ: Сводные отчёты или Полный доступ. По умолчанию — Сводные отчёты.
  5. Выберите Срок действия: 7 дней, 30 дней, 90 дней или 365 дней. По умолчанию — 90 дней.
  6. Нажмите Создать.

Над списком появится блок «Новый токен — скопируйте сейчас, повторно его не показать:».

Сохранение токена

  1. Нажмите Копировать в блоке с новым токеном. Кнопка сменится на «✓».
  2. Вставьте токен в настройки своей интеграции или в менеджер паролей.
  3. Закройте блок значком ✕ с подсказкой «Скрыть».

Токен выглядит как trk_ и 40 символов после него: цифры и буквы от a до f. Целиком он показывается один раз. Блок пропадает при закрытии, переходе на другую вкладку и обновлении страницы, а следующий созданный токен заменяет в нём предыдущий. В списке остаются только первые 12 символов.

Внимание.

Если токен не сохранён, посмотреть его повторно нельзя. Отзовите его и создайте новый.

Какой доступ выбрать

Доступ задаётся при создании и потом не меняется. У одного токена один вид доступа.

ДоступЧто может токен
Сводные отчётыСтроить отчёты и получать их в CSV, читать списки пользовательских метрик и типов конверсий. Группировки и фильтры — по кампаниям, потокам, офферам, лендингам, источникам, гео, устройствам и времени. Журналы кликов, фоновые выгрузки, sub_id, IP и другие параметры отдельного клика закрыты
Полный доступМенять данные и настройки в пределах прав создателя, включая управление доступом. Резервные копии, обновления, IP2Proxy и активация лицензии по токену недоступны

Точный список методов и полей отчёта для каждого доступа — на странице Admin API: обзор и авторизация.

Совет.

Создавайте отдельный токен на каждую интеграцию. Тогда один токен можно отозвать, не останавливая остальные, а в журнале действий видно, какая интеграция сделала запрос.

Токен «Расходы расширения»

В списке встречается третий вид доступа — Расходы расширения. Такой токен создаётся во вкладке Настройки → Расходы: блок Подключить профиль, кнопка Создать ключ. Он называется «Расходы · » и название профиля, действует 90 дней, создаётся только на платной лицензии и подходит только расширению расходов. Отзывается он во вкладке API, как и остальные токены. Подробнее — на странице Расширение для расходов Facebook.

Использование токена

Передавайте токен в заголовке Api-Key каждого запроса на домен панели:

bash
curl https://panel.example.com/api/v1/conversion-types \
  -H "Api-Key: trk_0123456789abcdef0123456789abcdef01234567"

Запрос возвращает список типов конверсий и подходит для токенов Сводные отчёты и Полный доступ. Успешный ответ — код 200. Базовый адрес и другие примеры — на странице Admin API: обзор и авторизация.

Запрос выполняется от имени пользователя, который создал токен, с его текущей ролью.

Список токенов

В списке — токены всей команды, новые сверху. Отозвать любой из них может владелец или администратор. В строке токена:

  • название;
  • вид доступа и срок: «До» и дата у действующего токена, «Истёк» и дата у просроченного, «Без срока · старый токен» у токена без срока;
  • первые 12 символов токена, «создан» с датой создания и «использован» с датой последнего запроса. Если токеном ещё не пользовались, вместо даты стоит «—».

Просроченный токен остаётся в списке, пока его не отзовут. Пока токенов нет, в блоке написано «Токенов нет.».

Когда токен перестаёт работать

  • Вышел срок действия. Срок изменить нельзя: создайте новый токен и замените его в интеграции.
  • Токен отозван.
  • Создатель токена удалён из команды или его роль стала ниже администратора. Его токены удаляются; после возврата роли их нужно создать заново. Подробнее о ролях — на странице Команда и роли.

Во всех трёх случаях запрос получает ответ 401 с сообщением invalid api key.

Отдельный случай — неактивная лицензия: токены не удаляются, но запросы получают ответ 402. После продления токены, у которых не вышел срок, продолжат работать. Подробнее — на странице Истечение лицензии: что закрыто и что работает.

Отзыв токена

  1. Найдите токен в списке по названию или первым символам.
  2. Нажмите значок ✕ с подсказкой «Отозвать» в его строке.
  3. Подтвердите действие в окне «Отозвать токен «…»? Все интеграции с ним перестанут работать.»

Токен исчезает из списка и перестаёт приниматься сразу. Вернуть отозванный токен нельзя.

Проверка

  1. Отправьте запрос из раздела Использование токена с новым токеном. Ответ с кодом 200 — токен работает.
  2. Откройте Настройки → API заново: список обновляется при открытии вкладки.
  3. Посмотрите строку токена: после слова «использован» стоит дата и время запроса.

Записи в журнале действий

Создание и отзыв токена записываются в Логи → Audit log с действием create или delete и ресурсом api-tokens. Запросы с токеном методами POST, PUT, PATCH и DELETE записываются туда же: в колонке Контекст у них стоит API, в колонке Пользователь — логин создателя и начало токена в квадратных скобках. Подробнее — на странице Audit log: журнал действий пользователей.

Если не получилось

invalid api key

Токен введён с ошибкой, истёк, отозван, либо его создатель удалён или больше не владелец и не администратор. Сравните начало токена со строками списка. Если токена в списке нет или у него стоит «Истёк», создайте новый.

API token scope does not allow this action

Метод не входит в доступ токена. Например, токеном Сводные отчёты вызван метод, которому нужен Полный доступ. Создайте токен с нужным доступом.

report includes fields outside the aggregate report scope

Токен Сводные отчёты запросил отчёт с группировкой или фильтром, которые ему закрыты, например по sub_id_1 или ip. Уберите такое поле или используйте токен Полный доступ. Разрешённые поля — в разделе Ограничения доступа «Сводные отчёты».

name is too long

Название длиннее 200 латинских или 100 кириллических символов. Сократите его и нажмите Создать снова.

expires_at must be in the next 365 days

Сообщение появляется при сроке 365 дней, если часы на компьютере спешат, даже на несколько секунд: срок считается от времени компьютера, а трекер сверяет его со своим временем. Синхронизируйте время на компьютере или выберите 90 дней.

Обновлено Нужна помощь? ↗