Типы ключей приёма

Приём событий различает не «ключи с настройками», а три разных типа ключей с разными границами доверия. Тип задаётся в момент выпуска, зашит в префикс значения и после этого не меняется. Права определяются именно типом: указать в запросе, что вы «на самом деле сервер», нельзя.

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

Три типа ключей

	Браузерный токен	Серверный ключ	Устаревший ключ
Префикс	pp_bt_…	pp_sk_…	pp_wk_…
Секретность	публичный по модели	секрет	фактически секрет
Где допустим	HTML, тег-менеджер, фронтенд-бандл	только окружение бэкенда	только там, где уже используется
Привязка к origin	обязательна, точный список	нет	нет
Срок действия	обязателен, по умолчанию 90 дней	не обязателен	без срока
Свои события	только из списка токена	любые, кроме pp.*	любые, кроме подтверждённых бизнес-фактов
Можно выпустить сейчас	да	да	нет

Граница доверия проходит по типу ключа и нигде больше. Поле source у события выводится из типа: браузерный токен всегда даёт browser, серверный — server. Заголовки X-PP-* и поле context в теле запроса — диагностические метаданные; они не повышают права и не меняют источник. Попытка объявить источник внутренним отклоняет все элементы батча.

Что разрешено каждому типу

Браузерный токен

Пять областей действия и ничего сверх: чтение публичной конфигурации сбора, запись событий, identify, запись сессий, захват элемента выбором на странице. Области identity:alias у него нет вообще — связывать идентификаторы браузерным токеном нельзя.

Что именно разрешено токену по умолчанию, сразу после выпуска:

• пять областей действия выше — ни больше, ни меньше;
• ровно одно собственное имя события — signup_completed. Если при выпуске список имён не задан, применяется именно этот узкий стартовый список; кабинет выпускает токен с ним же. Любое другое своё имя вернётся с отказом credential_event_forbidden на уровне отдельного элемента батча;
• встроенные события pp.* — просмотры страниц, клики, прокрутка, разделы, формы, записи и диагностика — списком не ограничены и работают независимо от него;
• список разрешённых origin — от 1 до 32 точных адресов, задаётся при выпуске;
• срок действия — 90 дней с момента выпуска, если явно не указан другой.

Список своих имён можно задать при выпуске: от 1 до 128 имён, каждое по маске ^[a-z0-9_.]{1,128}$, и ни одно не может начинаться с pp. — это пространство принадлежит встроенному сбору.

Есть одно дополнительное правило: если событие объявлено в реестре проекта как серверное, браузерный токен его не отправит даже при наличии имени в своём списке. Реестр в этом случае авторитетнее списка.

Серверный ключ

Три области действия: запись событий, identify и alias. Конфигурацию сбора он не читает, записи сессий и захват элементов ему недоступны.

Только серверный ключ принимается для подтверждённых бизнес-фактов. Полный список таких имён: registered, subscription_started, trial_started, trial_activated, trial_converted, trial_expired, payment_succeeded, payment_attached, order_created, first_order_created, order_paid, invoice_paid, refund. Из браузера ни одно из них не принимается — это граница доверия, а не настройка.

Обратное тоже верно: пространство pp.* серверному ключу закрыто, его формирует браузерный сбор.

Имена checkout_started и signup_completed намеренно не входят в список подтверждённых фактов: это сигналы интерфейса, и они остаются доступны браузеру через список токена.

Устаревший совместимый ключ

Такие ключи выпускались до разделения типов и несут старый широкий профиль: все шесть областей действия сразу, включая alias, без привязки к origin и без срока. Профиль не настраивается — он либо целиком такой, либо ключ считается некорректным.

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

Почему стоит уйти:

• один ключ совмещает публичные и секретные права, поэтому его нельзя безопасно положить ни в браузер, ни оставить только на сервере;
• нет ни списка origin, ни срока действия — утёкшее значение работает, пока его не отозвали вручную;
• источник события для такого ключа берётся из подсказки клиента, а не из типа ключа, поэтому разделение «браузер против сервера» в отчётах менее надёжно;
• только этот тип принимается в адресе запроса, а адреса попадают в логи прокси, CDN и систем мониторинга.

Права по эндпоинтам

Запрос	Браузерный токен	Серверный ключ	Устаревший ключ	Область действия
POST /v1/track	да	да	да	events:write
POST /v1/identify	да	да	да	identity:identify
POST /v1/alias	нет	да	да	identity:alias
POST /v1/replay	да	нет	да	replay:write
POST /v1/picker/capture	да	нет	да	picker:capture
GET /v1/cfg	да, с совпавшим origin	нет	да	config:read

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

Формат и передача ключа

Значение любого ключа устроено одинаково: pp_<тип>_<префикс>_<секрет>. Префикс — всегда 8 символов, секрет у браузерных и серверных ключей — всегда 32 символа, только латиница и цифры. Устаревшие ключи разбираются мягче: 8 символов префикса и секрет произвольной длины, чтобы выданные ранее значения не перестали работать.

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

Способы передать ключ:

Способ	Кому доступен	Примечание
Authorization: Bearer <ключ>	всем типам	основной способ
?key=<ключ> в адресе	только устаревшим	ответ помечается заголовком Deprecation: true
поле credential в теле JSON	только браузерному токену	только /v1/track и /v1/replay

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

Коды отказа

Ответ	Код	Когда возникает
401	unauthorized	ключ отсутствует, не разбирается, отозван, истёк или передан недопустимым способом
403	credential_scope_forbidden	тип ключа или его область действия не подходят для этого запроса
403	credential_origin_forbidden	origin браузерного запроса не совпал со списком токена
403	credential_rotation_required	ключ выпущен до разделения прав на связывание и требует ротации; только /v1/identify и /v1/alias
202	credential_event_forbidden	имя события недоступно этому типу ключа; отказ приходит по конкретному элементу батча

Сообщение при 401 одинаково для всех причин — по нему нельзя подбирать ключи. Ни один из этих ответов не возвращает присланное значение ключа или origin.

credential_rotation_required приходит с details.rotation_required. Ротация такого ключа решает вопрос, а до неё остальные запросы продолжают работать — ограничение касается только операций с идентификацией.

Разбор 403 и credential_event_forbidden по симптомам — в дереве диагностики.

Срок действия, ротация и отзыв

Браузерный токен обязан иметь срок. По умолчанию это 90 дней с выпуска; истёкший токен отвечает 401, как отозванный. Серверный ключ может быть бессрочным, для устаревших срок не задаётся вовсе.

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

Нужно	Ротация помогает	Что делать
Значение попало в чужие руки	да	ротация, затем замена значения в теге или окружении
Продлить срок токена	нет	выпустить новый токен
Добавить домен	нет	выпустить новый токен с полным списком доменов
Расширить список своих событий	нет	выпустить новый токен с нужным списком
Сменить тип ключа	нет	выпустить ключ нужного типа

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

Все три операции живут на экране Настройки → Проект, в секции «Credentials проекта»: там же видно тип каждого ключа, его префикс, области действия и origin, дату выпуска, срок и время последнего использования. Выпуск, ротация и отзыв доступны роли администратора и владельцу проекта; в демонстрационном проекте ключи приёма не выдаются.

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

Порядок, который не теряет события:

1. Выпустите браузерный токен: перечислите все origin, с которых открываются страницы, и все свои имена событий, которые сейчас отправляются из браузера.
2. Замените значение в теге или в вызове инициализации на новый токен. Совместимый атрибут data-key при этом лучше убрать: если указать и data-token, и data-key с разными значениями, скрипт молча не запустится.
3. Выпустите серверный ключ и переведите бэкенд на него, читая значение из переменной окружения.
4. Убедитесь, что события идут: ответ 202 с пустым rejected, свежие события на экране проверки интеграции. Проверьте оба источника — и браузер, и сервер.
5. Отзовите устаревший ключ.

Ротация устаревшего ключа сохраняет его тип: получится новое устаревшее значение, а не новый браузерный или серверный ключ. Для перехода нужен именно выпуск ключа нужного типа.

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

• В разметке и во фронтенд-бандле нет ничего, кроме браузерного токена. Поиск по префиксу серверного ключа по всему фронтенду и по контейнеру тег-менеджера — минута работы.
• Серверный ключ читается из окружения и не появляется в логах, в сообщениях об ошибках и в трассировках.
• У браузерного токена в списке origin есть все рабочие адреса, включая варианты с www и без, — подробности в настройке origin.
• Список своих событий токена совпадает с тем, что реально вызывает фронтенд, а подтверждённые бизнес-факты отправляются с бэкенда.
• В календаре есть напоминание о сроке браузерного токена: 90 дней проходят незаметно, а истечение выглядит как внезапный 401.