Безопасность

Хранение API-ключей

Никогда не храните API-ключи в исходном коде или системе контроля версий. Используйте переменные окружения или менеджер секретов (AWS Secrets Manager, HashiCorp Vault, Doppler).

# .env (добавьте в .gitignore!)
KONERGY_API_KEY=sk_konergy_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Загрузка в приложении
const apiKey = process.env.KONERGY_API_KEY;

• Добавьте .env в .gitignore
• В CI/CD используйте секреты платформы (GitHub Secrets, GitLab CI Variables)
• В продакшене используйте менеджер секретов вместо файлов окружения

Принцип минимальных привилегий

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

• Создавайте ключи организации с минимально необходимыми правами
• Устанавливайте spend limit на каждый ключ организации
• Разделяйте ключи по средам: отдельный ключ для dev, staging и production

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

Регулярно ротируйте API-ключи — рекомендуемый интервал составляет 90 дней. Подробная инструкция по безопасной ротации без простоя описана в руководстве Ротация ключей.

• Создайте новый ключ до отзыва старого (overlap period)
• Обновите все сервисы на новый ключ
• Убедитесь в отсутствии 401 ошибок
• Отзовите старый ключ

Idempotency

Всегда передавайте заголовок Idempotency-Key (UUIDv4) при всех мутациях (POST, PUT, PATCH, DELETE). Это защищает от дублирования операций при сетевых ошибках и повторных запросах.

POST /api/inference
Authorization: Bearer sk_konergy_...
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Подробнее об обработке конфликтов идемпотентности — в разделе Обработка ошибок.

Backend-only использование

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

• Не используйте префикс NEXT_PUBLIC_ для API-ключей: такие переменные попадают в клиентский JavaScript-бандл
• Не включайте API-ключи в клиентские переменные окружения или JavaScript-бандлы, доступные в браузере
• Проксируйте запросы к Konergy API через ваш backend
• Не передавайте ключ в URL-параметрах — используйте заголовок Authorization

Мониторинг

Настройте мониторинг для раннего обнаружения проблем с безопасностью.

• Отслеживайте неожиданные 401 Unauthorized ошибки — это может указывать на компрометацию или отзыв ключа
• Используйте Usage Analytics для отслеживания расходов по каждому ключу
• Настройте алерты при аномальном росте использования — резкий скачок может указывать на утечку ключа
• Логируйте request_id из ответов API для быстрой диагностики инцидентов

Организации

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

• Создайте отдельную организацию для каждой среды (dev, staging, production)
• Разделяйте организации по командам или проектам при необходимости
• Устанавливайте лимиты расходов как страховочную сетку — даже при утечке ключа расходы будут ограничены
• Регулярно проводите аудит списка участников и ключей организации — отзывайте доступ уволенных сотрудников