Авторизация

Для авторизации в API нужен ключ организации. Создайте его в кабинете, сохраните секрет в защищённом хранилище и передавайте в каждом запросе через заголовок Authorization: Bearer. Полное значение показывается только один раз: повторно посмотреть или восстановить старый ключ нельзя.

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

Использование API-ключа

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

1. Откройте раздел API-ключи.
2. Нажмите Создать ключ.
3. Укажите понятное название, например main-backend или test-worker. Так ключ легче найти в журнале и аналитике.
4. Создайте ключ и сразу скопируйте полное значение.

Секрет показывается только в окне после создания. В дальнейшем кабинет отображает безопасный префикс, но не полный ключ. Если секрет потерян, создайте новый: восстановить или повторно открыть старое значение нельзя.

Передача ключа в Bearer-заголовке

API принимает ключ в стандартном заголовке авторизации:

Authorization: Bearer <ВАШ_API-КЛЮЧ>

Например, так можно проверить доступ к списку моделей:

curl https://route.smartaipack.ru/v1/models \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"

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

Хранение ключа

Храните ключ только на сервере или в принятом в вашей инфраструктуре хранилище секретов. Для локальной разработки используйте переменную окружения в файле, который исключён из Git:

export AI_GATEWAY_API_KEY="<ВАШ_API-КЛЮЧ>"

Не передавайте ключ в клиентский JavaScript или мобильное приложение: пользователь сможет извлечь его из кода или сетевого запроса. Не записывайте полное значение в логи. Для разных сред и сервисов выпускайте отдельные ключи с понятными названиями — тогда один ключ можно заменить без остановки остальных интеграций.

Срок действия

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

В текущем кабинете настройка срока временно не показывается. Если у существующего ключа срок уже задан, учитывайте его при замене секрета и не ждите последнего дня. Сам срок не раскрывает ключ и не заменяет немедленный отзыв при утечке.

Отзыв и журнал действий

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

Журнал ключа показывает значимые действия, в том числе создание, отключение, включение, удаление и изменение срока, если оно выполнялось. Записи содержат время и автора действия. Фактические запросы проверяйте отдельно в разделе Использование, а расход и разбивку по ключам — в Аналитике.

Проверка нового ключа

После выпуска не переходите сразу к рабочей нагрузке. Сначала передайте новый секрет в тестовое окружение и выполните короткий запрос к /v1/models, показанный выше. Успешный ответ подтверждает, что переменная окружения прочитана, Bearer-заголовок собран правильно и ключ принят шлюзом.

Затем отправьте один короткий запрос к нужной модели и убедитесь, что он появился в журнале использования. Только после этого заменяйте секрет в рабочем окружении. Не печатайте значение переменной в консоль для проверки.

Что делать, если ключ раскрыт

Считайте ключ раскрытым, если он попал в публичный или чужой репозиторий, журнал, сообщение, скриншот, клиентский код либо был отправлен неизвестному получателю. Даже если утечка быстро удалена, секрет мог быть скопирован.

Действуйте в таком порядке:

1. Немедленно и безвозвратно отзовите ключ: удалите его в разделе API-ключи. Не ограничивайтесь временным отключением.
2. Создайте новый ключ с понятным названием и сохраните показанный один раз секрет.
3. Замените значение во всех средах, где использовался старый ключ: в рабочей, тестовой, фоновых заданиях и настройках развёртывания.
4. Проверьте новый ключ коротким запросом, затем убедитесь, что рабочие сервисы используют именно его.
5. Просмотрите журнал действий ключа, отдельные запросы и аналитику расходов. Обратите внимание на незнакомые модели, время и скачки расхода.

Старый ключ нельзя «восстановить» или безопасно использовать снова. Если вы видите неизвестные запросы, необычный расход или не можете быстро определить затронутые среды, обратитесь в поддержку. Не отправляйте поддержке полный новый ключ.