Обзор Валарм API¶
Валарм API обеспечивает взаимодействие компонентов системы Валарм. Вы можете использовать методы Валарм API для добавления, получения или изменения следующих сущностей:
-
уязвимости,
-
атаки,
-
инциденты,
-
пользователи,
-
клиенты,
-
WAF‑ноды и т.д.
Описание методов API доступно в справочнике API по ссылке:
Конечная точка API¶
Запросы API отправляются на следующий URL:
-
https://api.wallarm.com/
, если вы используете EU‑облако -
https://api.wallarm.ru/
, если вы используете RU‑облако
Аутентификация в API¶
В запросах к Валарм API необходимо передавать обязательные параметры аутентификации. Набор параметров зависит от клиента, с которого отправляется запрос:
-
Из интерфейса справочника API
-
С собственного клиента
Из интерфейса справочника API¶
Для аутентификации используется токен, полученный после входа в ваш аккаунт Валарм.
-
Войдите в ваш аккаунт Валарм по ссылке для EU‑облака или для RU‑облака.
-
Обновите справочник API по ссылке:
- https://apiconsole.eu1.wallarm.com/, если вы используете EU‑облако
- https://apiconsole.ru1.wallarm.ru/, если вы используете RU‑облако
-
Перейдите к нужному методу > секция Try it out, введите значения параметров и выполните запрос.
С собственного клиента¶
Для аутентификации используются ваши UUID и секретный ключ.
-
Войдите в ваш аккаунт Валарм по ссылке для EU‑облака или для RU‑облака → Настройки → Параметры для доступа к API.
-
Cкопируйте значение UUID.
-
Получите значение секретного ключа:
- Если вам известно значение секретного ключа, вы можете продолжить использовать это значение, так как в интерфейсе отображается значение активного секретного ключа, но в зашифрованном виде.
-
Если вам неизвестно значение секретного ключа или ключ был утерян, сгенерируйте новый секретный ключ с помощью кнопки Обновить секретный ключ и скопируйте полученное значение. Значение ключа отобразится только один раз.
Переиспользование секретного ключа
Кнопка Обновить секретный ключ генерирует новое значение секретного ключа и делает предыдущее значение невалидным. Для безопасного использования секретного ключа:
- Сохраните значение ключа в безопасном месте. Значение секретного ключа больше нигде не отобразится.
- Переиспользуйте сохраненное значение ключа во всех запросах к Валарм API.
- Если вы сгенерировали новое значение ключа, убедитесь, что предыдущее значение не используется на других клиентах API. Если предыдущее значение используется, замените его на новое.
-
Передайте UUID и секретный ключ в запросе к Валарм API:
- UUID в заголовке запроса в параметре
X-WallarmAPI-UUID
- Секретный ключ в заголовке запроса в параметре
X-WallarmAPI-Secret
- UUID в заголовке запроса в параметре
Подход к разработке и документированию API в Валарм¶
Валарм использует подход API-first, поэтому поведение новых возможностей продукта описывается в коде API, затем в справочнике. Обычно публикация изменений в коде API и обновление справочника API выполняются одновременно, но в некоторых случаях изменения в коде не затрагивают документацию API. Описание некоторых методов API может быть опубликовано в справочнике позже или не опубликовано, если методы предназначены для внутреннего использования.
Справочник Валарм API автоматически генерируется из swagger-файла с помощью инструмента Swagger UI. Справочник содержит описание методов API, параметров запроса и ответа и других атрибутов API. Вы можете выполнить любой описанный запрос через секцию Try it out справочника API.