API-ключи

API-ключи аутентифицируют каждый запрос к публичному Search API, конвейеру ингеста и Connector API. Панель открывает два представления ключей:

• /[orgSlug]/api-keys — все ключи во всех индексах организации (административный вид).
• /[orgSlug]/search → вкладка API Keys — ключи одного индекса (оперативный вид, привязан к индексу).

Эта страница описывает оба представления. Для использования на уровне запросов (заголовки, ошибки, семантика rate-limit) смотрите Search API → Публичный поисковый эндпоинт.

Типы ключей и префиксы

У каждого ключа есть типизированный префикс. Он хранится открытым текстом рядом с хэшем.

Админ-ключи (aa_admin_*) не создаются в панели — они провижинятся вне приложения и живут только на доверенных серверах.

Области ключа

У ключа одна или несколько областей (scopes), определяющих доступные эндпоинты.

Выбирайте минимально необходимую область. Виджету на маркетинговом сайте нужен только search. Воркеру Shopify — только connector_write. admin оставляйте для доверенных операторов и CI.

Как хранятся ключи

AACsearch никогда не хранит открытые ключи. При создании:

1. Сервер генерирует случайную секретную часть.
2. Полный ключ (префикс + секрет) показывается пользователю ровно один раз.
3. В БД сохраняются только SearchApiKey.prefix, SearchApiKey.hash (SHA-256) и метаданные (имя, области, allowed origins, лимит, срок).

Если потеряли открытый текст — восстановить нельзя. Создавайте новый ключ и отзывайте старый.

Модель БД — SearchApiKey в packages/database/prisma/schema.prisma. Открытый текст сверяется с хэшем при каждом запросе в packages/api/modules/search/lib/public-auth.ts.

Создание ключа

Из /[orgSlug]/search → вкладка API Keys:

1. Выберите целевой индекс из списка.
2. Нажмите Create Key.
3. Введите читаемое имя (например, storefront-widget-prod).
4. Выберите одну или несколько областей.
5. Необязательно: задайте срок действия.
6. Необязательно: задайте allowed origins (см. ниже).
7. Необязательно: переопределите лимит запросов на ключ (по умолчанию 600 в минуту).

После нажатия Create открытый текст ключа показывается один раз. Скопируйте его в секретное хранилище (Vault, AWS Secrets Manager) до закрытия диалога.

Allowed origins (белый список CORS)

Для ключей ss_search_*, идущих в браузер, можно зафиксировать список origin-ов. Запросы из других origin-ов отклоняются с HTTP 403.

• https://shop.example.com — продакшен-стор.
• http://localhost:3000 — локальная разработка.
• Пустой список — без проверки (ключ работает с любого origin — допустимо для серверных ключей, никогда для браузерных).

Проверка origin-ов происходит до контроля квот и лимитов. Это первая линия защиты для ключей, утёкших во фронтенд.

Лимиты запросов на ключ

У каждого ключа свой лимит со скользящим окном, по умолчанию 600 запросов в минуту. Превышение — HTTP 429 с error: "rate_limit_exceeded" и заголовком Retry-After.

Бакет лежит в SearchRateLimitBucket с ключом (keyId, windowStart). Можно ужесточить лимит на подозрительные ключи без отзыва — полезно при триаже.

См. Search API → Ошибки и лимиты — заголовки, форма ответа и общий квота-лимит организации.

Отзыв ключа

Нажмите Revoke на любом активном ключе. Отзыв мгновенный — следующий запрос отклоняется. Отозванные ключи остаются в списке зачёркнутыми ещё 90 дней, затем soft-удаляются (deletedAt).

Отзывайте ключ, когда:

• Он попал в публичный репозиторий или иначе утёк.
• Сотрудник с доступом к секрету ушёл.
• Коннектор выводится из эксплуатации.
• Идёт плановая ротация.

Ротация ключей

In-place ротации нет. Поток: создать → переключить → отозвать:

1. Создайте новый ключ с теми же областями.
2. Разверните его потребителю (виджет, воркер, сервер).
3. Подтвердите трафик на новом ключе на вкладке Активность в Аналитике.
4. Отзовите старый ключ.

Так обеспечивается нулевой даунтайм. Для браузерных виджетов выкатите новую сборку до отзыва — иначе пользователи с кэшированным HTML продолжат запрашивать со старым ключом и увидят ошибку.

Scoped-токены

Scoped-токены (ss_scoped_*) — короткоживущие подписанные токены, минтуемые из родительского поискового ключа. Они несут фильтр, AND-комбинируемый с клиентским. Они могут только сузить доступ (например, «только документы этого пользователя»), но не расширить.

Из панели они не создаются. Сервер минтует их на запросе через verifyScopedSearchToken(). См. Scoped Search Tokens.

Аудит-трейл

Каждое создание, отзыв и изменение области логируются в аудит:

См. Журналы аудита — фильтры, retention, экспорт.

Частые ошибки

Связанные страницы

• Рабочее пространство поиска — управление индексами, включая вкладку API Keys.
• Search API → Публичный поисковый эндпоинт — форма запроса и ответа.
• Scoped Search Tokens — мультитенантная фильтрация через подписанные токены.
• Ошибки и лимиты — полный каталог HTTP-ошибок.
• Журналы аудита — кто, что и когда делал.