{% extends "base.html" %} {% from 'partials/frontend_vendor.html' import vendor_api_docs_head %} {% block title %}Документация API — AWM{% endblock %} {% block extra_head %} {{ vendor_api_docs_head() }} {% endblock %} {% block content %}

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

Описание методов API для внешних интеграций. Используйте постоянный API-токен (awm_pat_…).

Базовый URL

{{ api_base_url }}

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

Bearer: awm_pat_…

Ответы

JSON; ошибки в поле detail

Спецификация

OpenAPI {{ openapi_version }} · /openapi.json

Скачать OpenAPI Открыть /docs Открыть /redoc

Быстрый старт

  1. Создайте постоянный API-токен в Профиль → Постоянные API-токены (нужно соответствующее право).
  2. Скопируйте секрет awm_pat_… — он показывается только один раз.
  3. Передавайте заголовок Authorization: Bearer awm_pat_… во всех внешних запросах к API.
  4. Схемы тел и ответов — во вкладках ReDoc или Swagger UI (Try it out в браузере использует cookie сессии UI).
Пример curl — профиль 
curl -sS -H "Authorization: Bearer awm_pat_<секрет>" \
  "{{ api_base_url }}/api/auth/me"
Пример ответа 200 
{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com",
  "roles": ["operator"],
  "permissions": ["notifications.send", "api_tokens.manage"],
  "theme": "dark"
}

Полные схемы тел, примеры запросов и возможные ответы (401, 403, 422, 503) — во вкладках ReDoc и Swagger UI. В документации отображаются операции /api/… по вашим правам; разделы администрирования и настроек платформы — только у администратора. Служебные UI/SSO и протоколы Worker/Agent в OpenAPI не входят.

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

Постоянный API-токен (внешний API)

  • Токен awm_pat_… для скриптов, CI и интеграций.
  • Создание: Профиль → Постоянные API-токены.
  • Секрет показывается один раз; в системе хранится только хеш.
  • Заголовок: Authorization: Bearer awm_pat_….
  • Scopes = пересечение с актуальными правами владельца на каждый запрос.
  • Роль администратора через PAT не наследуется автоматически.
  • Истечение пароля UI не блокирует PAT; доступны пауза и расписание.

Сессия веб-интерфейса

  1. Вход: POST /api/auth/login или форма UI.
  2. В ответе — access_token / refresh_token для установки cookie.
  3. Браузер передаёт cookie access_token автоматически.
  4. Обновление: POST /api/auth/refresh.

Сессионный JWT нельзя подставлять в Authorization: Bearer … для внешних клиентов — такой запрос получит 401. Для интеграций создайте PAT.

Отправка уведомлений

POST /api/notifications/send — создать уведомление в AWM из CI или внешней системы. Без целей в теле — отправка себе (владельцу токена). Другим пользователям / роли / группе — нужны соответствующие права на отправку другим.

curl — себе 
curl -sS -X POST "{{ api_base_url }}/api/notifications/send" \
  -H "Authorization: Bearer awm_pat_<секрет>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "CI",
    "message": "Сборка #42 упала",
    "type": "warning",
    "source": "jenkins",
    "url": "https://ci.example.com/job/42",
    "nav_label": "Открыть в Jenkins"
  }'
curl — другому пользователю 
curl -sS -X POST "{{ api_base_url }}/api/notifications/send" \
  -H "Authorization: Bearer awm_pat_<секрет>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "CI",
    "message": "Сборка #42 упала",
    "type": "warning",
    "username": "alice",
    "url": "https://ci.example.com/job/42"
  }'
Пример ответа 200 
{
  "ok": true,
  "sent": 1,
  "failed": 0,
  "recipients": [3],
  "type": "warning"
}

Права доступа

Наличие операции в OpenAPI не означает доступ без права — при недостаточных правах API вернёт 403. Назначить права: Администрирование → Роли. Эта страница доступна администратору или роли с правом на документацию API.

Ошибки

Код Когда Тело
400 Некорректный запрос / бизнес-ошибка {"detail": "payload должен быть объектом"}
401 Нет или недействителен токен; JWT вместо PAT {"detail": "Not authenticated"}
403 Недостаточно прав (RBAC / scopes PAT) {"detail": "Недостаточно прав"}
404 Ресурс не найден {"detail": "…"}
422 Ошибка валидации тела/параметров {"detail": [{"loc": ["body", "title"], "msg": "Field required", "type": "missing"}]}
503 Внешний PAT API отключён или режим технических работ {"detail": "Внешний доступ к REST API по постоянным токенам отключён"}

Отдельные протоколы

Не путайте пользовательский REST API с протоколами агентов и воркеров:

Протокол Префикс Аутентификация
Пользовательский API /api/… (кроме ниже) Bearer: только awm_pat_…
Worker API /api/worker/v1/… Bearer worker-токена узла
Agent API /api/monitoring/agents/… X-AWM-Agent-Token или Bearer agent-токена

Основные группы API

Полные схемы — во вкладках ReDoc или Swagger UI. Ниже — навигация по типовым сценариям интеграции.

Аутентификация и профиль /api/auth/* Вход, refresh, профиль, постоянные API-токены.
Ansible и запуски /api/playbooks · /api/runs · /api/commands Плейбуки, ad-hoc, история, расписания.
Инвентори и группы /api/inventories · /api/groups Хосты, группы доступа, привязки.
Секреты, ключи, переменные /api/secrets · /api/ssh-keys · /api/vars Учётные данные и переменные окружения.
Мониторинг /api/monitoring/* Хосты, метрики, агенты, библиотека, отчёты.
Инвентаризация активов /api/asset-inventory/* Карточки, операции, этикетки, аудит.
Terraform и редактор кода /api/terraform/* · /api/code-workspace/* Workspace, планы/apply, файлы проекта.
Плагины и уведомления /api/plugins · /api/notifications · POST /api/notifications/send · /api/statistics Плагины, центр уведомлений, отправка из внешних систем (`notifications.send` — себе, `notifications.send_others` — другим), статистика.
Администрирование /api/admin/* · /api/settings/* Пользователи, роли, бэкапы, системные настройки.
Worker API /api/worker/v1/* Протокол распределённых воркеров (отдельный токен узла).
{% endblock %}