REST API документация

Обзор возможностей API

API системы IDENTYX позволяет интегрированным приложениям получать доступ к следующим данным и функциям:

Аутентификация в API

Для работы с API используются следующие методы аутентификации:

Аутентификация приложения (client_id + client_secret)

Большинство API эндпоинтов требуют аутентификации через идентификатор приложения и секретный ключ. Эти данные вы получаете при создании OIDC приложения в IDENTYX:

• client_id — уникальный идентификатор вашего приложения
• client_secret — секретный ключ для безопасного доступа

Аутентификация через API-ключ

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

Аутентификация через сессию OIDC

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

Доступные API эндпоинты

Получение списка пользователей

Эндпоинт getUsers возвращает список всех пользователей, имеющих доступ к вашему приложению.

Что возвращается:

• Идентификатор пользователя (sub)
• Отображаемое имя (name)
• Имя пользователя (username)
• Email адрес (email)
• Права доступа (permissions) — массив прав в формате /объект:/действие
• Дата создания и обновления

Получение списка организаций

Эндпоинт getOrganizations возвращает список всех активных организаций в системе.

Что возвращается:

• Идентификатор организации (id)
• Название организации (title)

Комбинированный запрос пользователей и организаций

Эндпоинт getUsersAndOrganizations позволяет получить данные о пользователях и организациях одним запросом. Это удобнее и быстрее, чем делать два отдельных запроса.

Получение журнала безопасности

Эндпоинт getJournalData позволяет получить события из журнала безопасности IDENTYX с расширенными возможностями фильтрации и поиска.

Возможности фильтрации:

• По идентификатору события
• По приложению
• По пользователю
• По IP-адресу (частичное совпадение)
• По коду события
• По тексту события (частичное совпадение)
• По результату (успех/ошибка)
• По диапазону дат

Возможности сортировки:

• По любому полю (ID, дата, приложение, пользователь, IP, код, текст, результат)
• По возрастанию или убыванию

Пагинация:

• Можно указать номер страницы и количество записей на странице
• Максимум 500 записей за один запрос
• По умолчанию 50 записей на странице

Добавление событий в журнал

Эндпоинт putJournalEvent позволяет внешним приложениям добавлять события безопасности в централизованный журнал IDENTYX.

Что можно логировать:

• События аутентификации — входы и выходы пользователей
• Доступ к данным — просмотр, изменение, удаление
• Административные действия — изменения конфигурации
• Ошибки и угрозы — неудачные попытки, подозрительная активность
• Использование API — обращения к критичным эндпоинтам

Коды событий:

Система использует стандартные коды для классификации событий:

Код	Категория	Примеры использования
132	Успешная аутентификация	Пользователь успешно вошел в систему
133	Неуспешная аутентификация	Неверный пароль, блокировка
112	Использование API	Запросы к API, получение данных
113	Доступ к данным	Чтение, изменение, экспорт данных
114	Угроза безопасности	Подозрительная активность, атаки
103	Управление пользователями	Создание, изменение, удаление
107	Управление сессиями	Открытие, закрытие сессий

Получение объектов с учетными записями

Эндпоинт getUserObjectsWithCredentials возвращает список объектов (путей в дереве приложения), для которых у пользователя есть сохраненные учетные записи.

Параметры:

• user_id — идентификатор пользователя
• include_group_credentials — включить ли групповые учетные записи (по умолчанию true)

Что возвращается:

• Массив путей к объектам (например: /servers/web01, /databases/mysql01)
• Корневой объект обозначается как /

Получение лучших учетных записей для объектов

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

Как работает приоритизация:

1. Приоритет 1: Личные учетные записи с предпочтительным типом
2. Приоритет 2: Личные учетные записи с любым типом
3. Приоритет 3: Групповые учетные записи с предпочтительным типом
4. Приоритет 4: Групповые учетные записи с любым типом

Типы учетных записей:

• login_password — логин и пароль
• ssh_key — SSH ключи
• api_key — API ключи
• certificate — сертификаты
• token — токены доступа

Сценарии использования API

Синхронизация пользователей

Регулярно запрашивайте список пользователей через getUsers или getUsersAndOrganizations для синхронизации списка пользователей в вашем приложении с данными IDENTYX.

Рекомендуемая периодичность: каждые 5-15 минут

Централизованный аудит

Используйте putJournalEvent для отправки всех критичных событий из ваших приложений в единый журнал IDENTYX. Это позволит:

• Иметь единую точку для аудита всей инфраструктуры
• Отслеживать действия пользователей между приложениями
• Быстро реагировать на инциденты безопасности
• Соответствовать требованиям регуляторов

SSO с автоматической подстановкой учетных данных

Когда пользователь входит через OIDC и получает сессию, ваше приложение может:

1. Получить session_id из OIDC токена
2. Запросить учетные записи через getBestCredentialsForObjects
3. Автоматически подключиться к ресурсам от имени пользователя

Пользователь получает беспрепятственный доступ ко всем ресурсам без необходимости вводить пароли!

Мониторинг безопасности

Используйте getJournalData для построения дашбордов безопасности:

• Отслеживание неудачных попыток входа
• Мониторинг активности пользователей
• Анализ географии подключений (по IP)
• Выявление аномальной активности

Безопасность при работе с API

Оптимизация производительности

Кэширование данных

Рекомендуемое время кэширования для разных типов данных:

Тип данных	Рекомендуемое время кэша	Причина
Список пользователей	5-15 минут	Редко меняется, но требует актуальности
Список организаций	15-30 минут	Меняется очень редко
Учетные записи	1-5 минут	Может потребоваться быстрое обновление
Журнал безопасности (чтение)	Не кэшировать	Требуется актуальность в реальном времени

Объединение запросов

Вместо:

• Отдельный запрос getUsers
• Отдельный запрос getOrganizations

Используйте:

• Один запрос getUsersAndOrganizations

Это снижает нагрузку на сеть и ускоряет получение данных!

Асинхронное логирование

При отправке событий через putJournalEvent:

• Не блокируйте основной процесс приложения
• Используйте очереди сообщений для асинхронной отправки
• Группируйте события и отправляйте пакетами
• Не отправляйте более 100 событий за один запрос

Обработка ошибок

Все API эндпоинты возвращают результат в формате JSON с полем status:

• status: "success" — успешное выполнение, данные в поле data
• status: "error" — ошибка выполнения, описание в поле error

Частые ошибки

Ошибка	Причина	Решение
Приложение не найдено	Неверные client_id или client_secret	Проверьте данные приложения в настройках IDENTYX
Неверный API ключ	Неверный ключ для журнала безопасности	Получите актуальный ключ у администратора
Не указан session_id	Отсутствует обязательный параметр	Передайте session_id в запросе
Сессия не найдена или истекла	Неверный или устаревший session_id	Пользователь должен войти заново
Пользователь не найден	Указан несуществующий user_id	Проверьте корректность идентификатора

Ограничения API

• Журнал безопасности: максимум 500 записей за один запрос
• События безопасности: рекомендуется до 100 событий за один запрос
• Частота запросов: не устанавливается жестко, но рекомендуется не более 1 запроса в секунду для одного приложения

Как получить API-ключ для журнала безопасности

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

1. Обратитесь к администратору системы IDENTYX
2. Администратор сгенерирует уникальный API-ключ в настройках системы
3. Сохраните ключ в безопасном месте (переменные окружения, хранилище секретов)
4. Используйте ключ в заголовке X-API-KEY при запросах к getJournalData

Связанные разделы

Для более глубокого понимания интеграции с IDENTYX изучите следующие разделы:

• OIDC интеграция — как интегрировать приложение через OpenID Connect
• Proxy интеграция — прозрачная аутентификация через IDENTYX Proxy
• API учетных записей — детальное описание работы с учетными данными
• Обзор журнала событий — понимание структуры журнала безопасности
• Обзор OIDC — основы протокола OpenID Connect