Сессия встраивания

POST /api/v1/embed/session
Authorization: Bearer aac_live_…

Ключ aac_live_… не должен попадать в браузер. Этот эндпоинт решает именно эту задачу: он обменивает ключ на токен сессии встраивания, привязанный к одному индексу, одному действию (search:read) и сроку жизни. На страницу попадает токен (data-aac-token), ключ остаётся на вашем сервере.

Эндпоинта GET /embed/bootstrap и формы ?key= не существует. Ключ в строке запроса, data--атрибуте или HTML страницы — это именно та утечка, которую эта схема устраняет: эндпоинт читает ключ только из заголовка Authorization, в остальных случаях отвечает 401 UNAUTHORIZED.

Вызывайте его из собственного бэкенда — обработчика маршрута, SSR-прохода или шага сборки — и передавайте полученный token на страницу.

Выпуск сессииCopy Anchor Link

curl -sS -X POST "$AAC_API/embed/session" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "index": "documentation", "expires_in": 900 }'

Тело необязательно. Нечисловой expires_in или слишком длинный index — это 422 VALIDATION_ERROR.

{
	"ok": true,
	"token": "aac_sess_…",
	"token_type": "embed_session",
	"scope": ["search:read"],
	"index": { "slug": "documentation", "name": "Documentation" },
	"expires_at": "2026-10-23T11:15:02.000Z",
	"expires_in": 900,
	"settings": {
		"placeholder": "Поиск по документации…",
		"perPage": 8,
		"queryBy": "title,content",
		"facets": ["category"],
		"showStats": true,
		"showRecent": true,
		"showVoice": false,
		"showImage": false,
		"showRelated": false,
		"accent": "#2563eb",
		"dark": false,
		"sortOptions": [
			{ "label": "По релевантности", "value": "default" },
			{ "label": "Сначала новые", "value": "created_at:desc" }
		]
	},
	"ui": { "name": "AACSearch UI", "version": "1.0.0" },
	"request_id": "req_4a6c8e0b2d4f6a8c0e2b4d6f"
}

Что гарантирует ответ:

• Токен только для поиска. Он несёт search:read и ничего больше, поэтому не может писать, удалять или переиндексировать. Компрометация страницы даёт креденшл, который истекает сам и читает только то, что страница и так показывает.
• Токен привязан к одному индексу и тенанту. Фильтр тенанта применяется на сервере в каждом запросе; браузер не видит ни инфраструктурного ключа, ни хоста, ни имени коллекции.
• Токен истекает. По умолчанию 900 секунд, максимум 3600. Для долгоживущих страниц выпускайте новый заранее; истёкший токен — 401 EMBED_SESSION_EXPIRED.
• Ответ не кешируется. Заголовок cache-control: no-store; каждый выпуск записывается в журнал аудита (embed.session.issue).
• Настройки живые. settings берутся из SearchIndex.settings.embed, поэтому изменения в панели оформления консоли применяются при следующей загрузке страницы — без передеплоя.

Список разрешённых originCopy Anchor Link

Если у ключа заданы allowedOrigins, браузерный вызов с любого другого origin получает 403 ORIGIN_NOT_ALLOWED и не получает CORS-заголовков. Пустой список означает «любой origin». Поскольку эндпоинт сессии предназначен для вызова из вашего бэкенда, серверный вызов не несёт заголовка Origin и проверке не подвергается.

НастройкиCopy Anchor Link

ОшибкиCopy Anchor Link

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Send the API key as an Authorization header; embed sessions cannot be minted from a query parameter",
		"request_id": "req_7b9d1f3a5c7e9b1d3f5a7c9e"
	}
}

Эндпоинты, принимающие токенCopy Anchor Link

Когда на странице есть токен, виджет обращается только к этим эндпоинтам. Все они аутентифицируются токеном — в JSON-теле (token) или, где указано, заголовком Authorization: Bearer aac_sess_… — и никогда API-ключом. Каждый также отвечает на CORS-preflight (OPTIONS) кодом 204.

Поиск через прокси проходит тот же конвейер, что и публичный API (журнал запросов, правила, значения по умолчанию, ослабление запроса, did-you-mean), поэтому аналитика видит трафик виджета. Каждый embed-поиск списывается с квоты searches тенанта.

Ошибки токена на этих эндпоинтах:

Доступ из браузераCopy Anchor Link

Для виджета и собственного браузерного интерфейса используйте POST /embed/session и /embed/search. Ваш сервер обменивает API-ключ на короткоживущий токен; браузер не получает инфраструктурных ключей и имён хранилищ. Расширенный эндпоинт /scoped-key не используется виджетом и не заменяет поисковый API платформы.