Жизненный цикл API-ключа: область доступа, ротация и аварийный отзыв

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

Начните с паспорта ключа

Для каждого ключа зафиксируйте систему-владельца, потребителя, окружение, назначение, набор прав, дату выпуска, ожидаемую ротацию и контакт ответственной команды. Имя вида prod-key-2 почти бесполезно: через год никто не понимает, какой процесс остановится после отзыва.

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

Ограничьте доступ до выдачи

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

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

Такой подход соответствует принципу постоянной проверки, разобранному в материале об архитектуре Zero Trust: доверие к сети не должно автоматически давать доверие к действию.

Доставляйте секрет без копирования вручную

Ключ не должен попадать в Git, тикет, wiki, образ контейнера или общий чат. Приложение получает его из менеджера секретов или защищённой конфигурации во время запуска. Журналировать следует идентификатор секрета и факт доступа, но не само значение.

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

Ротация без простоя

Надёжная схема на короткое время поддерживает два действующих ключа:

1. создать новый ключ с теми же минимальными правами;
2. доставить его потребителю;
3. переключить приложение и подтвердить успешные запросы по новому идентификатору;
4. остановить использование старого ключа;
5. отозвать старый ключ после ограниченного окна наблюдения;
6. проверить, что обращений с ним больше нет.

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

Сделайте аудит полезным

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

Подробнее о границах и изменениях самого интерфейса — в материале про версионирование API-контрактов.

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

Подготовьте аварийный отзыв

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

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

Хороший API-ключ — не вечная строка. Это ограниченная сервисная идентичность, которую можно найти, заменить, отозвать и связать с конкретным потоком запросов.