Получение ключей

Ключ — это то, чем запрос к приёму событий доказывает, что он относится к вашему проекту. Без ключа события не принимаются, а с чужим ключом попадут в чужой проект. Здесь — операция: где ключ взять, что с ним сделать сразу и как его заменить.

Разбор типов ключей, их прав и границ доверия — в статье Ключи и границы доверия. Эта страница отвечает на вопрос «получить и не потерять».

Где выдаются ключи

В кабинете два места, и оба работают с одними и теми же ключами проекта:

• «Настройки → Установка трекера» — здесь ключ выпускается рядом с готовым примером подключения и сразу подставляется в него.
• «Настройки → Проект», раздел «Credentials проекта» — полная таблица всех ключей проекта с ротацией и отзывом.

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

Ключ всегда принадлежит одному проекту. Один ключ на два проекта выдать нельзя — если проектов два, ключей тоже два. Демо-проекту ключи не выдаются вовсе: вкладка установки трекера показывает пояснение и предлагает создать свой проект.

Какие ключи бывают

Тип	Префикс	Где хранится	Что может
Браузерный токен	pp_bt_	в коде страницы, публичен по своей модели	отправлять события, identify, записи сессий, читать настройки сбора
Серверный ключ	pp_sk_	только в переменных окружения или менеджере секретов	отправлять события, identify и связывать идентификаторы
Устаревший ключ	pp_wk_	ключи, выпущенные до разделения на два типа	совмещает оба набора прав

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

При выпуске браузерного токена нужно заполнить одно поле — «Разрешённые origins»: точные адреса вида https://app.example.com, по одному в строке или через запятую. Wildcard, путь, query, фрагмент и логин с паролем в адресе запрещены; origins можно указать до 32. Новый браузерный токен получает срок действия 90 дней и стартовый список разрешённых имён событий из одного значения — signup_completed. Серверный ключ дополнительных полей не требует и по умолчанию выдаётся без срока.

Полное значение показывается один раз

Сразу после выпуска кабинет открывает окно с полным значением ключа. Это единственный раз, когда оно видно.

В базе данных ActionPulse хранит только необратимый хеш полного значения и безопасный префикс из восьми символов — тот, что виден в таблице ключей. Список ключей никогда не возвращает само значение, поэтому:

Что сделать в момент выпуска:

• Серверный ключ — перенести в менеджер секретов или в переменные окружения сервиса. В кабинете он остаётся только в этом окне.
• Браузерный токен — вставить в тег или в конфигурацию сборки и сохранить там же, где хранится остальная конфигурация приложения. Повторно полное значение тоже не покажут.

Ротация

Ротация — замена значения с сохранением всего остального. Кнопка «Ротировать» есть у любого не отозванного и не истёкшего ключа, включая устаревший.

Что происходит:

• выпускается новое значение и показывается один раз, как при первом выпуске;
• старое значение немедленно перестаёт приниматься — события с ним отклоняются с кодом 401;
• тип ключа, его права, список разрешённых origins и срок действия остаются прежними. Ротацией их изменить нельзя — для другого набора прав выпускается новый ключ.

Истёкший ключ ротировать нельзя: запрос вернёт ошибку проверки. Для него остаётся только отзыв, а вместо него выпускается новый ключ.

Отзыв

Отзыв выключает ключ навсегда. У отозванного ключа не остаётся ни ротации, ни восстановления — в таблице он получает статус «Отозван».

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

Отзывайте ключ, если:

• значение попало в публичный репозиторий, в чат, в тикет или в логи;
• ключом пользовался подрядчик или сотрудник, который больше не работает с проектом;
• вы выпустили замену и убедились, что события идут через неё.

Кто имеет право

Выпуск, ротация и отзыв ключей — право ролей admin и owner (полный список ролей: owner, admin, analyst, viewer).

Роли analyst и viewer не видят даже таблицу ключей: список ключей проекта закрыт той же проверкой, что и их изменение. Это сделано намеренно — префикс ключа и список origins тоже являются сведениями о конфигурации проекта.

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

Чего с ключами делать нельзя

• Не помещайте pp_sk_ в браузер. Ни в тег, ни в переменную сборки фронтенда, ни в адрес страницы. Кабинет отдельно предупреждает об этом, если серверный ключ вставить в поле браузерного примера.
• Не коммитьте ключи в репозиторий и не подставляйте значение прямо в команду терминала: она попадёт в историю оболочки.
• Не передавайте ключ в query-параметре. Приём принимает такой транспорт только для устаревших ключей и помечает ответ заголовком Deprecation: true. Правильный способ — заголовок Authorization: Bearer.
• Не отправляйте браузерным токеном то, чему нужно доверять. Оплаты, заказы, возвраты и регистрации принимаются только серверным ключом; попытка отправить их браузерным токеном вернёт отказ по конкретному событию. Подробнее — Отправка событий с бэкенда.
• Не используйте один ключ для нескольких контуров. Отдельный ключ для стейджинга позволяет отозвать его, не задев продакшен.

Переход с устаревшего ключа

Если в проекте остался ключ pp_wk_, переходите по порядку:

1. Выпустите браузерный токен pp_bt_ с точным списком origins.
2. Замените значение в браузере на новый токен и дождитесь, пока события пойдут.
3. Выпустите серверный ключ pp_sk_ и переведите на него бэкенд.
4. Убедитесь, что доставка идёт с обеих сторон — по колонке «Использован» в таблице ключей и по экрану проверки интеграции.
5. Отзовите устаревший ключ.

Порядок важен: устаревший ключ совмещает оба набора прав, поэтому пока он активен, часть трафика может незаметно продолжать идти через него.

Что проверить

1. В таблице ключей у нужного ключа статус «Активен», а не «Истек» или «Отозван».
2. У браузерного токена в колонке прав указан именно тот origin, с которого работает сайт, и срок действия ещё не подходит к концу.
3. В колонке «Использован» появилась отметка — значит, ключом реально воспользовались. Отметка отстаёт от факта не более чем на минуту, поэтому сразу после первого события её может ещё не быть.
4. События видны на экране проверки интеграции — Проверка интеграции.

Если приём отвечает 401, ключ отозван, истёк или не подходит для этого транспорта. Если 403 с упоминанием origin — адрес страницы не совпадает со списком разрешённых. Разбор по кодам — в Решении проблем.