API-ключи

AACsearch выпускает три семейства API-ключей. У всех одно правило хранения: в БД хранится только SHA-256-хэш ключа. Исходный ключ показывается ровно один раз при создании. Если его потерять — нужно создать новый: восстановить старый мы не можем.

Семейства ключей

ss_connector_* ключи существуют, чтобы CMS-плагин мог ротироваться независимо от ключа дашборда мерчанта. Хэш у них совпадает со ss_search_* с тем же телом — это операционное, а не криптографическое разделение.

Области (scopes)

У каждого постоянного ключа одна или несколько областей:

Области проверяются на каждом запросе. search-ключ при обращении к ingest-эндпоинту получает 403. Чего вы не выдали — того у ключа нет.

Модель хранения

При создании ключа сервер:

1. Генерирует 32 случайных байта и кодирует их в base64url.
2. Добавляет префикс семейства (ss_search_, ss_connector_, …).
3. Сохраняет sha256(rawKey) (hex) в search_api_key.hash.
4. Сохраняет первые 12 символов в поле prefix, чтобы дашборд показывал, например, ss_search_AB….
5. Возвращает исходный ключ в ответе один раз.

Исходный ключ нигде не логируется, не пишется на диск открытым текстом и не покидает строку БД, в которой лежит его хэш. Если БД скомпрометируют — атакующий получит хэши, но не сможет ими пользоваться против API.

Сравнение хэшей — константное по времени (crypto.timingSafeEqual), чтобы API не подсказывал, какие ключи существуют.

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

В дашборде:

1. Откройте Project → API keys.
2. Нажмите Create key.
3. Назовите ключ по имени системы, которая будет им пользоваться (frontend-search-eu, ingest-worker-prod).
4. Выберите минимально необходимые области.
5. Опционально: ограничьте список индексов.
6. Опционально: задайте allow-list по Origin. См. Allow-list по Origin.
7. Опционально: задайте rate limit в минуту.
8. Опционально: укажите дату истечения.
9. Нажмите Create, скопируйте ключ один раз и сохраните в secret-менеджере.

Программно — POST /api/orpc/searchApiKey.create.

Ротация

Любой ключ с admin-областью ротируйте минимум раз в 90 дней. Браузерные ключи можно чаще.

Рекомендуемая процедура (без downtime):

1. Создайте новый ключ с теми же областями и ограничениями.
2. Выкатите новый ключ в конфигурацию приложения (env, secret-менеджер). Старый ключ пока оставьте.
3. Проверьте в дашборде в колонке «Last used», что новый ключ принимает трафик, а старый затих.
4. Отзовите старый ключ.

Если ключ возможно скомпрометирован — пропускайте плавный путь и сразу идите к Отзыву.

Отзыв

Отзыв проставляет revokedAt в строке. Следующая верификация возвращает invalid_or_revoked_key (HTTP 401). Никакого grace period и кэша, который нужно подождать, нет.

В дашборде: Project → API keys → Revoke. Программно: POST /api/orpc/searchApiKey.revoke.

Если ключ утёк

1. Сразу отзовите. Не нужно ждать расследования.
2. Выпустите замену с теми же областями и выкатите.
3. Проверьте журнал аудита. См. Аудит. Отфильтруйте по префиксу ключа, поищите неожиданных вызывающих.
4. Просканируйте аналитику на запросы, не похожие на вашу нагрузку.
5. Переиндексируйте данные, которые мог затронуть admin или ingest ключ.

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

• Коммит ключей в Git. Добавьте ss_search_, ss_connector_, ss_scoped_ в правила секрет-сканера.
• Один admin-ключ повсюду. Одна утечка ломает все окружения. Заводите по ключу на сервис и окружение.
• admin в браузерном коде. Браузерный ключ — search + allow-list по Origin или scoped-токен. Иначе любой посетитель получает право мутировать ваши данные.
• Забыли про allow-list по Origin. Без него атакующий, выдрав ключ из JS-бандла, сможет ходить к API откуда угодно. См. Allow-list по Origin.

См. также

• Scoped-токены — короткоживущие токены поверх API-ключа
• Allow-list по Origin — ограничение по источникам
• Аудит — кто и когда пользовался ключом
• Best practices — общий чек-лист