API-ключи

API-ключи обеспечивают безопасный доступ к данным SOBERIS через REST API. Они позволяют аутентифицировать запросы и контролировать доступ к конкретным эндпоинтам.
Требования безопасности
API-ключи предоставляют полный доступ к данным. Храните их в безопасности и никогда не передавайте третьим лицам.
Создание API-ключа

Для создания нового API-ключа необходимо иметь роль api_keys_management. API-ключи создаются через веб-интерфейс системы.
Шаги создания:

  1. Перейдите в раздел управления API-ключами в системе
  2. Нажмите кнопку "Создать ключ"
  3. Заполните обязательные поля: Название ключа: уникальное имя (3-100 символов, только латиница), Владелец: имя владельца ключа (3-100 символов, только латиница), Эндпоинты: выберите доступные операции
  4. Нажмите "Создать ключ"
  5. Скопируйте и сохраните сгенерированный ключ в безопасном месте
Важно!
API-ключ отображается только один раз при создании. Обязательно сохраните его, так как восстановить его будет невозможно.
Доступные эндпоинты

При создании API-ключа можно выбрать доступ к следующим операциям:
  • start-transaction - Начало транзакции для работы с данными
  • insert-one - Вставка одной записи в базу данных
  • delete-one - Удаление одной записи из базы данных
  • finish-transaction - Завершение транзакции и фиксация изменений
  • update-one - Обновление одной записи в базе данных
  • search - Поиск и получение данных из базы
Использование API-ключа

API-ключ передается в заголовке SBRS-API-Keyпри выполнении запросов к эндпоинтам /sbrs-data/*.

Пример запроса
curl -X POST "https://your-domain.com/sbrs-data/search" \
  -H "Content-Type: application/json" \
  -H "SBRS-API-Key: your-api-key-here" \
  -H "SBRS-Correlation-Id: unique-correlation-id" \
  -H "SBRS-Originator: your-application" \
  -H "SBRS-Message-Id: unique-message-id" \
  -d '{
    "query": {
      "field": "value"
    }
  }'
Обязательные заголовки
Аутентификация и авторизация

Система использует JWT токены для аутентификации API-ключей. Каждый токен содержит:
  • Название ключа
  • Владельца ключа
  • Список доступных эндпоинтов
  • Время создания
  • Цифровую подпись для верификации
Процесс валидации
  1. Система извлекает токен из заголовка SBRS-API-Key
  2. Парсит JWT токен и извлекает метаданные
  3. Проверяет существование ключа в кэше или базе данных
  4. Сравнивает хеш токена с сохраненным значением
  5. Проверяет права доступа к запрашиваемому эндпоинту
  6. При успешной валидации разрешает выполнение запроса
Управление API-ключами

Просмотр ключей

В интерфейсе управления отображается список всех созданных API-ключей с информацией:
  • Название ключа
  • Владелец
  • Дата создания
  • Пользователь, создавший ключ
Список доступных эндпоинтов
Удаление ключей

API-ключи можно удалить через интерфейс управления. При удалении ключ немедленно перестает работать и удаляется из кеша Redis.
Внимание!
Удаление API-ключа необратимо. Все приложения, использующие этот ключ, перестанут работать немедленно.
Кеширование и производительность

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

При работе с API-ключами могут возникать следующие ошибки:
Лучшие практики
🔐 Безопасность
  • Никогда не передавайте API-ключи через незащищенные каналы
  • Не храните ключи в коде приложения или репозиториях
  • Используйте переменные окружения или безопасные хранилища секретов
  • Регулярно ротируйте API-ключи
Устранение неполадок
Проблема: Ошибка 401 Unauthorized
Возможные причины:
  • Отсутствует заголовок SBRS-API-Key
  • Неверный формат токена
  • Токен был удален или изменен
Решение: Проверьте наличие и корректность всех заголовков запроса.
Проблема: Ошибка доступа к эндпоинту
Возможные причины:
  • Ключ не имеет доступа к запрашиваемому эндпоинту
  • Неверно указан путь в запросе
Решение: Создайте новый ключ с необходимыми правами или проверьте URL запроса.
Проблема: Медленные запросы
Возможные причины:
  • Проблемы с Redis кешем
  • Высокая нагрузка на базу данных
  • Сетевые задержки
Решение: Проверьте состояние системы мониторинга и логи приложения.