Описание API
Список методов, параметры запросов и форматы ответов поддерживаются в Swagger. В верхней части Swagger можно переключаться между Public API v1 и Backend API.
IDENTYX поддерживает несколько способов интеграции. Интеграции с учетными данными OIDC-приложения продолжают работать, а для роботов пользователь может выпускать собственные токены приложений (PAT).
Две API-поверхности
Небольшой версионированный контракт для новых интеграций. Его методы и структуры данных меняются редко.
Выбранные методы существующего API приложений. Они удобны для автоматизации текущих сценариев, но могут меняться вместе с интерфейсом приложения.
В Backend API рядом с каждой операцией указан используемый способ аутентификации. Методы, принимающие client_id + client_secret или OIDC-сессию, продолжают работать независимо от PAT. Методы PAT Backend API доступны только тогда, когда соответствующая поверхность выбрана в токене.
Что доступно через API
Получение сведений о пользователях, имеющих доступ к интегрированному приложению.
Получение структуры проектов, доступной интегрированному приложению.
Получение подходящих личных и групповых учетных данных для разрешённых сценариев подключения.
Способы аутентификации
OIDC-приложение: client_id + client_secret
Этот способ используется существующими серверными интеграциями, в том числе приложениями платформы INFRAX. Идентификатор и секрет выдаются при создании OIDC-приложения. Такой доступ принадлежит самому приложению и не является пользовательским PAT.
Храните client_secret только на серверной стороне. Не помещайте его в браузерный код, открытые репозитории и журналы.
Пользовательский токен приложения (PAT)
PAT позволяет передать роботу часть доступа пользователя без передачи логина, пароля или интерактивной OIDC-сессии. Токен передаётся как Authorization: Bearer <PAT> и может использовать выбранные при выпуске API-поверхности.
PAT работает от имени выпустившего его пользователя. Он не может получить больше доступа, чем есть у владельца, и дополнительно ограничивается выбранными при выпуске приложениями, источниками прав и проектами.
OIDC-сессия пользователя
Активная OIDC-сессия применяется в интерактивных сценариях, где приложение выполняет действие от имени вошедшего пользователя, например при безопасной автоподстановке сохранённых учетных данных.
Какой способ выбрать
| Сценарий | Подходящий способ |
|---|---|
| Существующая серверная интеграция самого приложения | client_id + client_secret |
| Робот действует от имени пользователя без интерактивного входа | PAT |
| Действие выполняет вошедший пользователь | OIDC-сессия |
Кто может выпускать токены
Кнопка Создать токен доступна супер-администратору и пользователю с разрешением Выпуск токенов приложений. Пользователь выпускает токены только от своего имени. В режиме «Смотреть как» выпуск и управление токенами недоступны.
Выпуск токена
Мастер выпуска открывается так:
- В меню слева в группе Мои откройте Секреты.
- Перейдите на вкладку Токены приложений.
- Нажмите Создать токен.
Шаг 1. Приложения
Выберите приложения, к которым будет обращаться робот. Для каждого приложения отметьте Public API v1, Backend API или обе поверхности. Рядом с поверхностью доступна ссылка на её Swagger.
При выборе приложения мастер по умолчанию отмечает доступные для него поверхности. Лишнюю поверхность можно снять вручную.
Шаг 2. Границы доступа
Выберите, из каких источников PAT получит разрешения:
- Личные права — права, назначенные непосредственно пользователю;
- группы — права выбранных групп пользователя;
- системная группа «Все» — общие права всех пользователей, если они подходят выбранным приложениям.
Мастер показывает только те группы, которые дают хотя бы одно разрешение для выбранных приложений и API-поверхностей. Рядом с каждой группой указано количество подходящих разрешений.
Флажок Все доступные в блоке источников прав включает личные права и все показанные группы. Такой же флажок в блоке проектов включает все доступные пользователю проекты.
«Все доступные» означает все варианты, доступные в момент выпуска. Новая группа или проект, добавленные владельцу позднее, автоматически не расширят уже выпущенный токен.
Шаг 3. Проверка и выпуск
На последнем шаге мастер формирует краткое название из выбранных приложений и пометки (все) или (ограничено). Название можно изменить. Здесь же задаётся срок действия токена.
Перед выпуском IDENTYX проверяет выбранные границы и показывает количество итоговых технических разрешений. Если выбранные источники не дают ни одной подходящей операции, мастер предложит вернуться и изменить выбор.
Нажмите Выпустить токен после успешной проверки.
Сохранение и проверка секрета
Скопируйте PAT до закрытия окна. IDENTYX хранит только защищённый хеш и не сможет показать этот секрет повторно.
В окне выпущенного токена можно:
- скопировать секрет и готовый пример cURL;
- выбрать одно из приложений и выполнить безопасный тестовый запрос;
- открыть Swagger выбранной API-поверхности.
Как ограничивается доступ
- PAT получает только права выбранных личных и групповых источников.
- PAT работает только в выбранных проектах.
- Отдельного выбора объектов в мастере нет. Для объектов продолжают действовать те же ACL выбранных источников и владельца; токен не получает доступ ко всем объектам автоматически.
- Новые права владельца не расширяют уже выпущенный PAT.
- Удалённые у владельца права сразу перестают работать и через PAT.
Управление выпущенными токенами
На вкладке Токены приложений отображаются имя и безопасный префикс токена, состояние, приложения, количество выбранных групп и проектов, срок действия и последняя активность.
Список сужают кнопкой Фильтры: по состоянию, имени или префиксу и приложениям. Приложения отмечают в окне Отбор по приложениям — можно несколько, в списке останутся токены, выданные хотя бы на одно из них. Супер-администратору доступен ещё отбор Чьи токены: свои или все.
Для выпущенного токена доступны следующие действия:
- Подробнее — посмотреть выбранные приложения, поверхности, группы, проекты и итоговые технические разрешения;
- Продлить на 30 дней — изменить срок действия, не меняя секрет;
- Ротировать секрет — выпустить новый секрет; старый немедленно перестаёт работать;
- Отозвать — окончательно отключить токен. Отзыв необратим.
Токен также перестаёт работать после окончания срока, удаления или деактивации владельца. Временная блокировка владельца временно останавливает и его PAT.
Форматы ответов
- Существующие интеграционные методы сохраняют свой прежний JSON-конверт с полями
status,dataилиerror. - Public API v1 использует HTTP-статусы и безопасное описание ошибки в формате
application/problem+json. - Backend API сохраняет формат ответа исходного backend-метода.
Безопасность
- Используйте API только через HTTPS.
- Не записывайте PAT,
client_secret, идентификаторы сессий и расшифрованные учетные данные в журналы. - Выбирайте для PAT только необходимые приложения, API-поверхности, источники прав и проекты.
- Ротируйте скомпрометированный секрет и отзывайте токены, которые больше не используются.
Связанные разделы
- Личные учетные записи — хранилище секретов и вкладка токенов приложений
- OIDC интеграция — интерактивный вход пользователей
- Учетные данные в интеграциях — работа подключенных приложений с сохранёнными секретами
- Разработка OIDC приложений — практические примеры интеграции