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

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

Чтобы поменять API-ключ AI Gateway без остановки сервиса, сначала создайте новый ключ, сохраните его в защищённом хранилище и постепенно переведите на него приложения. Старый ключ на время перехода оставьте действующим. Когда новый трафик подтверждён, сначала отключите старый ключ, выдержите окно отката и только затем удалите его.

Управление ключами выполняется в кабинете AI Gateway. Создавать, отключать, снова включать и удалять ключи организации может её активный администратор. Обычному участнику организации эти действия и организационная аналитика недоступны.

Зачем менять ключи

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

Плановая ротация полезна, когда:

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

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

Стратегия без остановки

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

Порядок важен:

Выпустить новый ключ.
Развернуть его в приложениях.
Подтвердить запросы по новому ключу и отсутствие запросов по старому.
Перевести старый ключ в disabled.
После окна отката удалить старый ключ.

Отключение обратимо: ключ со статусом disabled можно снова включить. Удаление необратимо, поэтому между этими действиями нужно оставить окно отката, заранее определённое командой.

Ротация через кабинет

Шаг 1. Создать новый ключ

Откройте раздел API-ключей в кабинете и нажмите «Создать ключ». Укажите понятное название. Полный секрет показывается только один раз — сразу перенесите его в защищённое хранилище секретов и закройте окно лишь после сохранения.

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

Для названия удобно использовать схему «среда — сервис — назначение — дата или версия», например prod-orders-chat-2026-08. Название не должно содержать сам секрет или другие чувствительные данные.

В текущем кабинете при создании задаётся название ключа. Самостоятельная настройка срока действия сейчас скрыта, поэтому не включайте её в обязательную процедуру ротации.

Шаг 2. Обновить приложения

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

Меняйте приложения по одному. Пока старый ключ остаётся active, необновлённые экземпляры продолжают работать, а обновлённые уже отправляют запросы с новым ключом.

Не храните два секрета в коде и не выводите их командами диагностики. Инструкции по безопасной передаче ключа в запросе собраны в материале «Авторизация в API».

Шаг 3. Проверить переход трафика

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

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

Журнал ключа подтверждает административные действия — создание, отключение, повторное включение и удаление. Он не заменяет проверку трафика: для перехода смотрите именно использование и аналитику.

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

Шаг 4. Отключить старый ключ

Когда все приложения переведены и новый ключ подтверждён, нажмите «Отключить» у старого ключа. Его статус изменится с active на disabled, и запросы с ним перестанут проходить.

После отключения проверьте основные сценарии, фоновые задания и редкие интеграции. Если обнаружился забытый потребитель, старый ключ можно временно вернуть в active кнопкой «Включить», завершить перевод и повторить проверку.

Продолжительность окна отката задаёт ваша команда. Для сервиса с редкими заданиями оно должно охватывать хотя бы один их полный рабочий цикл.

Шаг 5. Удалить после окна отката

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

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

Аварийная ротация при утечке

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

Дальше:

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

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