API-ключи, области доступа, ограничения и кредиты

Каждый запрос к API арендатора содержит API-ключ организации в заголовке X-NOVA-API-KEY. У ключа одна из двух областей доступа (scope).

Полные ключи

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

Поисковые ключи — ключи для браузера

Поисковый ключ предназначен для размещения на странице витрины магазина, в мобильном приложении или в виджете. Он даёт доступ только к операциям, отмеченным в контракте как x-nova-key-scope: search:

На всё остальное API отвечает 403. Поисковый ключ не может записывать документы, а также читать или изменять конфигурацию, поэтому худшее, что можно сделать со скопированным ключом, — выполнять поиск.

Заголовок сессии

Браузерные клиенты передают X-NOVA-SESSION-ID — один идентификатор на вкладку браузера. Именно он связывает события посетителя для аналитики и A/B-тестов, определяет, к какой сессии относится диалог, и служит основой для учёта лимита AI-операций поискового ключа. При работе с поисковым ключом AI-операции требуют этот заголовок (без него — 400); диалог, начатый в одной сессии, нельзя прочитать или продолжить из другой (403). Пакеты aacsearch-ui и облегчённый виджет передают его автоматически.

Ограничения ключа

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

Принудительный фильтр всегда объединяется через AND с собственным filter_by вызывающего и никогда им не заменяется:

// ключ: forcedFilterBy = { "products": "tenant_id:=42" }
GET /v1/collections/products/documents/search?q=drill&filter_by=in_stock:=true
// движок получает
filter_by=(in_stock:=true) && (tenant_id:=42)

Ограничения применяются до поисковых правил и A/B-экспериментов, поэтому те могут только сузить ограниченный поиск, но не расширить его.

Где они действуют

Не только в обычном searchCollection. Те же проверки выполняются на каждом пути чтения, который возвращает документы:

• multiSearch: каждый элемент проверяется по своей коллекции; один элемент с запрещённой коллекцией отклоняет весь пакет с 403.
• Ассистент (createChatCompletion, streamChatCompletion): запрещённые коллекции исключаются из поиска контекста (403, если не осталось ни одной), а источники из предыдущих ходов перепроверяются по текущему ключу.
• getRecommendations, suggestQueries и presearchQueries.
• searchSemantic, searchByImage и searchByVoice.

Защищённые (дочерние) ключи

Браузерный ключ, выпущенный через createBrowserKey (POST /browser-keys, см. ключи виджета), — это подписанный токен nssk_…, производный от родительского полного ключа и нигде не хранящийся. Он принимает allowed_collections, allowed_origins, rate_limit_per_minute, user_token и expires_in_seconds (не более семи дней), ограничен областью search, а ограничения родителя продолжают действовать. Они объединяются так, что дочерний ключ может только сузить родителя:

• Коллекции и поля пересекаются. Списки без общих элементов запрещают всё и никогда не превращаются в «без ограничений».
• Принудительные фильтры объединяются по каждой коллекции (и по *): если оба ключа задают одну запись, фрагмент дочернего ключа добавляется к родительскому через AND — дочерний ключ может добавить фильтр, но не заменить его.
• Лимит запросов: действует меньший из двух.
• Origin и IP: список, заданный дочерним ключом, используется вместо родительского; иначе действует родительский.

Отзыв или ротация родительского ключа делает недействительными все производные от него ключи.

Кредиты: как оплачиваются операции AI

У вашей организации есть кошелёк кредитов (1 кредит = 1 минимальная денежная единица). Каждый вызов модели оплачивается из него, независимо от того, каким ключом выполнен запрос: платформа запускает модели с собственными ключами провайдеров и списывает с вас кредиты:

Перед запуском модели стоимость оценивается и резервируется; после завершения списывается фактическая стоимость, а остаток резерва освобождается. Если кошелёк не покрывает резерв, API отвечает 402 с указанием доступной и необходимой суммы. Неудачный вызов модели ничего не стоит. Каждое списание — это запись в журнале операций, которую можно просмотреть в консоли; она называется по имени операции (assistant.chat, voice.transcription, search.image, …).

Кошелёк новой организации открывается с небольшим пробным балансом; тарифы добавляют включённые в них кредиты при активации, а пополнить кошелёк можно в любой момент.

Квоты и лимиты

Запросы учитываются в месячной квоте тарифа (429, когда она исчерпана). Поскольку поисковый ключ размещается в браузере и может быть оттуда скопирован, AI-операции, выполненные с ним, дополнительно ограничены для каждой сессии посетителя — фиксированным числом в минуту, после чего API отвечает 429 со значением retry_after. Полные ключи принадлежат серверу и так не ограничиваются.

Ответы с ошибками

Для каждой операции документированы 401 (ключ отсутствует или отозван), 403 (область доступа) и 429 (квота или лимит); операции, тарифицируемые в кредитах, также возвращают 402. Сгенерированные SDK выбрасывают для каждого случая типизированную ошибку — UnauthorizedError, ForbiddenError, PaymentRequiredError, TooManyRequestsError, — поэтому витрина магазина может показать «ассистент недоступен» вместо трассировки стека.