Корпоративный контроль и доверие30 июля 2026 г.Flatkey Team

Лучшие практики управления API-ключами для ИИ-продуктов (чек-лист на 2026 год)

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

Лучшие практики управления API-ключами для ИИ-продуктов (чек-лист на 2026 год)

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

Это руководство превращает перечисленные принципы в чек-лист для команд платформы, безопасности и ИИ-продуктов. В нем рассмотрены жизненный цикл ключа, шаблон реестра ключей, ротация без простоев, защитные меры в CI/CD, регламент реагирования на инциденты и код для генерации, хранения и проверки ключей. Среди источников — памятка OWASP по управлению секретами, рекомендации Google Cloud по работе с API-ключами и документация GitHub по сканированию секретов; все источники проверены 27 октября 2026 года.

Лучшие практики управления API-ключами: краткий чек-лист

#	Рекомендация	Что предотвращает
1	Никогда не прописывайте ключи в исходном коде, ноутбуках или клиентских приложениях	Утечки через историю Git, браузерные бандлы и бинарные файлы мобильных приложений
2	Держите ключи провайдеров на сервере; выдавайте клиентам короткоживущие токены сессии	Извлечение ключа с устройства пользователем или вредоносной программой
3	Используйте отдельный ключ для каждой среды, приложения и участника команды	Остановку всех систем при отзыве одного утекшего ключа
4	Применяйте самые строгие доступные ограничения: API, модели, IP-адреса, квоты	Использование украденных ключей для любых целей
5	Храните ключи в менеджере секретов, а не в тикетах, чатах или вики	Появление копий, которые невозможно найти или заменить при ротации
6	Ведите реестр ключей с владельцами, рабочими нагрузками и датами ротации	Сбои при ротации у неизвестных потребителей ключа
7	Выполняйте ротацию по расписанию с периодом одновременной работы ключей, затем отзывайте старый ключ	Сохранение действующих ключей после ухода сотрудников и прекращения работы с подрядчиками
8	Удаляйте ключи, которыми больше не пользуетесь	Существование забытых ключей с действующими правами
9	Включите сканирование секретов и защиту при отправке изменений	Попадание ключей в публичный или общий репозиторий
10	Никогда не записывайте в логи ключи или заголовки авторизации; записывайте ID или версию ключа	Утечки секретов через логи, трассировки и отчеты об ошибках
11	Задавайте лимиты расходов и настраивайте оповещения о необычной активности	Неожиданные счета из-за украденного ключа или вышедшего из-под контроля использования
12	Подготовьте регламент реагирования, в котором отзыв ключа имеет приоритет	Длительное сохранение доступа, пока команды выясняют, воспользовался ли кто-то утечкой

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

Жизненный цикл API-ключа

OWASP рекомендует управлять секретами на протяжении всего жизненного цикла: создание, ротация, отзыв и истечение срока действия, с аудитом на каждом этапе (памятка OWASP по управлению секретами). Для API-ключа ИИ-сервиса этот цикл выглядит так:

Этап	Действие владельца	Что фиксировать
Запрос	Обосновать необходимость рабочей нагрузки, среды и моделей	Тикет или запись в реестре
Создание	Сгенерировать ключ в консоли или через API провайдера и дать ему понятное имя	ID ключа, время создания, создателя
Ограничение	Ограничить модели, API, сети и бюджет	Настройки ограничений
Хранение	Сохранить прямо в менеджер секретов; больше никуда не вставлять	Путь к секрету и политику доступа
Доставка	Передать во время выполнения только той рабочей нагрузке, которой он нужен	Привязку в конфигурации развертывания
Мониторинг	Отслеживать запросы, токены, расходы и время последнего использования	Панель мониторинга использования и оповещения
Ротация	Создать замену, переключить потребителей, проверить	Запись о ротации
Отзыв	Аннулировать ключ у провайдера, подтвердить ответ 401	Время отзыва и результат проверки

Пять границ, которые может пересекать ключ ИИ-сервиса

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

Граница	Типичная ошибка	Необходимая мера защиты
От клиента к приложению	Ключ провайдера встроен в браузерный бандл, бинарный файл мобильного приложения, настольное приложение или расширение	Держите ключи провайдеров на сервере; выдавайте клиентам короткоживущие учетные данные пользователя или сессии
От приложения к шлюзу	Все сервисы используют один ключ без ограничений	Используйте удостоверения рабочих нагрузок, токены шлюза с ограниченными правами, квоты и явную политику маршрутизации
От шлюза к провайдеру	Одни учетные данные дают доступ ко всем моделям, проектам или средам	Разделяйте ключи по провайдерам, средам, рабочим нагрузкам и уровням риска, где это поддерживается
От запроса к логам	Заголовки авторизации, промпты, файлы или ответы попадают в трассировки	Исключайте поля с секретами, минимизируйте логирование содержимого запросов, токенизируйте идентификаторы и проверяйте удаление чувствительных данных
Действия сотрудников	Ключи вставляют в тикеты, чаты, регламенты или инструменты поддержки	Используйте контролируемые процедуры доступа, аудит получения секретов, процедуры экстренного доступа и автоматическое истечение срока действия

Такая карта границ меняет вопрос проектирования с «Где хранить ключ?» на «Какое удостоверение позволяет выполнить какой запрос, с какими данными, по какому маршруту и какие свидетельства останутся после этого?».

Храните ключи на серверной стороне

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

Более безопасная схема:

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

Клиенту не нужен секрет провайдера. Он получает только право вызывать ваш продукт в заданных вами пределах.

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

Создайте реестр ключей до начала ротации

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

Как минимум фиксируйте:

Поле	Пример	Зачем это нужно
ID секрета	`prod-support-chat-anthropic-01`	Стабильная внутренняя ссылка, не содержащая значение секрета
Провайдер и проект	Учетная запись провайдера + идентификатор проекта	Определяет масштаб последствий во внешней системе
Среда	Разработка, предварительное тестирование, эксплуатация	Не дает тестовым системам получить права производственной среды
Рабочая нагрузка	`support-chat-api`	Позволяет учитывать использование и адресно отзывать доступ
Владелец	Команда и график дежурств	Определяет ответственных во время инцидентов
Место хранения	Путь в менеджере секретов или привязка в конфигурации развертывания	Показывает, где находится основной источник данных
Разрешенные модели/маршруты	Разрешенное семейство моделей или политика шлюза	Ограничивает непредусмотренное использование
Лимиты расходов и запросов	Бюджет рабочей нагрузки, RPM, TPM или ограничения параллелизма	Ограничивает злоупотребления и неконтролируемую автоматизацию
Создание и последняя ротация	Временные метки	Позволяет выявлять устаревшие учетные данные
Способ ротации	Два ключа, псевдоним версии или окно обслуживания	Исключает изменения без подготовки
Зависимости при отзыве	Сервисы, которые нужно обновить первыми	Защищает доступность
Классификация данных	Публичные, внутренние, конфиденциальные, регулируемые	Связывает политику ключей с правилами работы с промптами

Не включайте значение ключа в реестр. Храните только метаданные и ссылку на секрет в управляемом хранилище.

Разделяйте удостоверения по средам, рабочим нагрузкам и риску

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

Предпочитайте отдельные удостоверения для:

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

Применяйте ограничения везде, где провайдер их предоставляет. Они могут охватывать разрешенные API, модели, исходные сети, проекты, источники перехода, приложения или квоты. Например, рекомендации Google Cloud по API-ключам включают ограничение и изоляцию ключей, удаление ненужных ключей, исключение их из коммитов и мониторинг использования.

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

Рассматривайте правила работы с промптами и логами как часть управления ключами

API-ключ разрешает передачу данных по определенному пути. Если защищать ключ, но не контролировать этот путь, основной риск, специфичный для ИИ, останется нерешенным.

Перед маршрутизацией запроса классифицируйте его содержимое и применяйте принцип минимальной необходимости:

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

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

Полезная запись о событии в производственной среде может содержать:

{
  "request_id": "req_01J...",
  "tenant_id_hash": "tnt_7f2...",
  "workload": "support-chat-api",
  "route_policy": "support-low-risk-v3",
  "provider": "selected-provider",
  "model": "selected-model",
  "input_tokens": 842,
  "output_tokens": 211,
  "latency_ms": 1370,
  "status": 200,
  "key_version": "v12",
  "redaction_policy": "customer-support-v4"
}

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

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

Спроектируйте ротацию API-ключей без простоев

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

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

Создайте новый ключ провайдера. Примените такие же или более строгие ограничения, чем у старого ключа.
Сохраните его как новую версию секрета. Не перезаписывайте старое значение, если платформа поддерживает версии или псевдонимы.
Разверните потребителей, поддерживающих новую версию. Обновите шлюз или рабочие нагрузки, чтобы они получали секрет по текущему псевдониму или версии.
Переключите трафик и наблюдайте. Убедитесь, что запросы с новой версией ключа проходят успешно, используются ожидаемые модели, а расходы, лимиты частоты запросов и доля ошибок соответствуют ожиданиям.
Устраните использование старого ключа. Проверьте реестры развертываний, задания, воркеры и среды аварийного восстановления.
Отзовите старый ключ. Недостаточно перестать им пользоваться — аннулируйте его у провайдера.
Проверьте отказ в доступе. Контролируемый тест должен подтвердить, что старые учетные данные больше не работают.
Зафиксируйте результаты. Сохраните время действий, владельцев, затронутые рабочие нагрузки, результаты проверки и дату следующего пересмотра.

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

type ProviderCredential = {
  value: string;
  version: string;
};

async function loadProviderCredential(): Promise<ProviderCredential> {
  const activeVersion = await secretStore.resolveAlias("ai/provider/active");
  const value = await secretStore.readVersion("ai/provider", activeVersion);

  return { value, version: activeVersion };
}

Не выводите value, не сериализуйте возвращенный объект и не прикрепляйте его к ошибке. Записывайте в логи только идентификатор версии, не содержащий секрет.

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

Не допускайте попадания секретов в репозитории и логи CI

Менеджер секретов не поможет, если учетные данные скопированы в исходный код, фикстуру, артефакт сборки или лог CI.

Применяйте защитные меры на трех этапах:

Перед коммитом

Предоставляйте файлы .env.example с заглушками, никогда не включайте в них действующие учетные данные.
Не добавляйте локальные файлы с секретами в систему контроля версий.
Запускайте быстрый сканер секретов в хуках pre-commit для поиска типовых форматов ключей провайдеров и значений с высокой энтропией.
Объясняйте разработчикам, что удаление секрета в последующем коммите не удаляет его из истории.

При отправке изменений и создании pull request

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

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

Во время CI/CD

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

Отслеживайте использование, не записывая секрет в логи

Хороший мониторинг отвечает на вопрос «Кто воспользовался какими полномочиями?», не сохраняя сами учетные данные.

Отслеживайте:

Рабочую нагрузку, среду, арендатора или проект и версию ключа.
Провайдера, модель, политику маршрутизации и резервный маршрут.
Количество запросов, объем токенов, расходы, задержку и класс ошибки.
Исходную сеть или удостоверение развертывания, если это полезно.
Доступ к менеджеру секретов, включая отклоненные запросы на чтение.
Создание ключей, изменение ограничений, ротацию, отзыв и удаление.
Неожиданное использование из другой среды, географической точки, с другой моделью или в необычное время.

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

Меры управления трафиком, дополняющие защиту учетных данных, описаны в руководстве по лимитам запросов LLM и практическом руководстве по резервной маршрутизации LLM API.

Измеряйте время от обнаружения утечки до отзыва

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

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

Признайте учетные данные потенциально скомпрометированными. Зафиксируйте, когда и где они могли быть раскрыты.
Создайте замену по обычной контролируемой процедуре. Не вставляйте новый ключ в чат ради ускорения работы над инцидентом.
Переключите легитимные рабочие нагрузки на замену. Используйте подготовленную процедуру ротации.
Отзовите подозрительный ключ. Если немедленный отзыв приведет к неприемлемому ущербу, изолируйте маршруты и снизьте лимиты, пока завершается переключение.
Проверьте все места, где могут быть копии. Изучите историю исходного кода, логи CI, артефакты, слои контейнеров, системы поддержки, панели мониторинга, ноутбуки, локальную конфигурацию и резервные копии.
Проверьте разрешенные пути доступа к данным. Определите, к каким промптам, ответам, файлам, инструментам или моделям ключ мог давать доступ, а не только какие расходы он позволял совершать.
Сопоставьте активность. Сравните использование у провайдера, логи шлюза, развертывания, чтение секретов и действия пользователей.
Уведомите нужных ответственных. Подключите команды безопасности, платформы, юристов, специалистов по защите персональных данных и работе с клиентами с учетом затронутых данных и договоров.
Устраните первопричину. Добавьте недостающий сканер, ограничение, границу доступа по удостоверениям или фильтр логов.
Зафиксируйте время. Запишите время до обнаружения, создания замены, переключения трафика, отзыва и проверки.

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

Если вы выдаете API-ключи своим клиентам

Многие ИИ-продукты также выдают ключи, например чтобы клиенты могли вызывать вашего агента или встраивать вашу функцию. Те же практики применимы и с другой стороны:

Генерируйте ключи криптографически стойким генератором случайных чисел, обеспечивая не менее 32 байт энтропии.
Добавляйте узнаваемый префикс (например, sk-fk- у ключей Flatkey), чтобы сканеры секретов и команда поддержки могли распознавать утекшие ключи. Партнерская программа GitHub использует известные форматы токенов для уведомления эмитентов, когда ключ отправляют в публичный репозиторий (сканирование секретов GitHub).
Показывайте полный ключ один раз, а затем храните только хеш. При утечке базы данных ключи останутся в безопасности.
Отображайте в панели управления только маскированный префикс, а также дату создания и время последнего использования.
Обеспечьте немедленный отзыв и возвращайте 401 для отозванных ключей.
Позвольте клиентам ограничивать права ключей конкретными моделями, проектами или лимитами расходов.

Python: генерация, хеширование и проверка ключей

import hashlib
import hmac
import secrets

PREFIX = "sk-acme-"

def new_api_key() -> tuple[str, str]:
    """Return (plaintext key shown to the user once, hash to store)."""
    key = PREFIX + secrets.token_urlsafe(32)  # 32 random bytes
    return key, hashlib.sha256(key.encode()).hexdigest()

def verify(presented: str, stored_hash: str) -> bool:
    candidate = hashlib.sha256(presented.encode()).hexdigest()
    return hmac.compare_digest(candidate, stored_hash)  # constant-time compare

key, digest = new_api_key()
print(key[:12] + "...")   # show the full key once in the UI, never log it
print(verify(key, digest))  # True

Быстрый хеш, например SHA-256, здесь допустим, поскольку ключ длинный и случайный, в отличие от придуманного человеком пароля. Храните хеш, ID ключа, владельца, область разрешенного доступа и временные метки.

Node.js: загрузка ключа из окружения и запрет работы при его отсутствии

// Never fall back to a hardcoded default key.
const apiKey = process.env.FLATKEY_API_KEY;
if (!apiKey || !apiKey.startsWith("sk-fk-")) {
  throw new Error("FLATKEY_API_KEY is missing or malformed");
}

const res = await fetch("https://router.flatkey.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-haiku-5-5",
    messages: [{ role: "user", content: "ping" }],
    max_tokens: 5,
  }),
});
console.log(res.status); // log the status, never the header

Убедитесь, что отозванный ключ действительно не работает

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

# Expect 401 for the revoked key; do not echo the key itself
OLD_KEY="$(cat /run/secrets/old_flatkey_key)"
status=$(curl -s -o /dev/null -w "%{http_code}" \
  https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $OLD_KEY")
if [ "$status" = "401" ]; then echo "revoked OK"; else echo "STILL ACTIVE: $status"; fi

Записывайте результат и время в журнал ротации. В документации Flatkey указано, что отзыв происходит немедленно и любой запрос с отозванным ключом получает 401 Unauthorized, без льготного периода (документация Flatkey по API-ключам).

Как Flatkey поддерживает эти практики

Flatkey предоставляет единую совместимую с OpenAI конечную точку (https://router.flatkey.ai/v1) для множества провайдеров моделей, поэтому по вашим сервисам распределено меньше ключей провайдеров. Согласно документации Flatkey по API-ключам (проверена 27 октября 2026 года):

Можно создавать несколько ключей: по одному на среду, приложение или участника команды, с понятными именами вроде prod-customer-chatbot.
Полный ключ sk-fk- показывается только один раз. После этого на странице ключей отображаются имя, дата создания, время последнего использования и маскированный префикс.
Отзыв происходит немедленно, поэтому разверните новый ключ до отзыва старого.
Все ключи используют общий баланс учетной записи и по умолчанию имеют доступ ко всем моделям. Используйте Группы в консоли, чтобы ограничить ключ конкретными моделями или задать квоту расходов.

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

Эталонная архитектура ИИ-продуктов с несколькими провайдерами

Безопасную конфигурацию с несколькими провайдерами можно организовать в пять уровней:

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

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

Чек-лист для производственной среды

Используйте этот чек-лист перед запуском и при ежеквартальной проверке защитных мер.

Хранение ключей и удостоверения

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

Хранение и доставка

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

Данные и наблюдаемость

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

Ротация и реагирование

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

Частые вопросы

Каковы лучшие практики управления API-ключами?

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

Стоит ли хранить API-ключ в переменной окружения?

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

Как часто нужно менять API-ключи?

Выбирайте интервал с учетом риска и защитных механизмов провайдера; многие команды меняют ключи ИИ-сервисов в производственной среде каждые 90 дней и немедленно проводят ротацию при кадровых изменениях или подозрении на раскрытие. Главное — отработанная процедура ротации, отзыв старого ключа и проверка отзыва.

Может ли браузерное или мобильное приложение обращаться к ИИ-провайдеру напрямую с API-ключом?

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

Что делать, если API-ключ утек на GitHub?

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

Безопаснее ли один ключ шлюза, чем множество ключей провайдеров?

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

Как хранить API-ключи, которые я выдаю своим пользователям?

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