Публичные и приватные ключи

Каждый ассистент может иметь несколько ключей доступа. Ключ передаётся в заголовке X-Assistant-Key при любом запросе к /integration/v1/* и однозначно определяет, какой ассистент отвечает и что позволено в рамках этого запроса.

Роль `pk_` — публичный ключ

Для чего: гостевые чаты — hosted-ссылка (см. «Ссылка на чат») и виджет, встроенный на публичной странице.

Что может:

Создавать и продолжать гостевые (Guest) чаты — без привязки к конкретному покупателю.
Вызывать Public-инструменты ассистента.

Что не может:

Утверждать личность покупателя — если в запросе с pk_-ключом передать поле customer, сервер ответит ошибкой 422. Это осознанное ограничение: публичный ключ виден в браузере кому угодно, и если бы он мог задавать customer.externalId, любой посетитель мог бы притвориться чужим покупателем.
Использовать Personal- и Private-инструменты (они просто не видны в таком чате).

Почему его можно использовать в браузере: pk_-ключ разрешает только анонимное общение от имени случайного посетителя — скомпрометировать он может не больше, чем скомпрометировала бы открытая форма обратной связи на сайте. Максимум, что можно сделать с чужим pk_-ключом — попытаться исчерпать общий лимит запросов ассистента (requestsPerMinute) или прочитать Public-инструменты, которые и так предназначены для гостей.

Origin-ограничение: при создании ключа можно указать список разрешённых Origin — тогда ключ будет принят только с запросов от этих доменов (проверяется заголовок Origin браузера). Пустой список = ключ примут с любого домена. Для hosted-ссылки, которой вы делитесь напрямую (не встраивая в свой сайт), оставляйте список пустым — иначе страница на нашем домене получит 403.

Роль `sk_` — приватный ключ

Для чего: серверная интеграция, где вы уже знаете, кто пишет (клиент вашего сайта, авторизованный у вас).

Что может:

Создавать личные (Personal) чаты, привязанные к конкретному покупателю (customer.externalId — обязателен при создании чата этим ключом).
Использовать Personal- и Private-инструменты, в том числе с серверными параметрами вроде customer_id (см. «Инструменты»).

Что не может (точнее, что вы не должны допускать):

Показываться в браузере. sk_-ключ — это как пароль от базы данных: если он попадёт в клиентский JavaScript, любой посетитель вашего сайта сможет писать от имени любого вашего покупателя, просто подставив чужой externalId. Приватный ключ вызывается только с вашего сервера, который сам аутентифицирует пользователя и передаёт корректный externalId.

Сравнение

	`pk_` Публичный	`sk_` Приватный
Где хранится	Можно в браузере	Только на сервере
Тип чата	Guest (анонимный)	Personal (привязан к покупателю)
Поле `customer` в запросе	Запрещено (`422`)	Обязательно при создании чата
Origin-ограничение	Опционально	Не применяется
Типичный сценарий	Hosted-ссылка, виджет на сайте	Чат внутри вашего личного кабинета/приложения

Одноразовый показ

Полный ключ (fullKey) показывается только один раз — в момент создания или ротации. Дальше в базе остаётся только хэш, восстановить значение невозможно. Если ключ потерян — не пытайтесь угадать или восстановить, создайте новый (или используйте ротацию, если старый ключ ещё активен).

Ротация и отзыв

Отзыв — немедленно и безвозвратно останавливает работу ключа. Все интеграции, использующие его, начнут получать 401.
Ротация — отзывает старый ключ и создаёт новый с тем же именем и настройками (Origin и т.д.), показывая новый fullKey один раз. Используйте, если подозреваете, что ключ скомпрометирован, но хотите сохранить его настройки.

Отозванные ключи остаются в списке (со статусом «Отозван») — это история для аудита, они не удаляются физически.