API на портала

Порталът е обикновен клиент на документирано REST API под /api/v1. Всичко, което прави порталът, можете да направите и чрез API.

Пълният справочник на крайните точки (endpoints) е справочникът на API, генериран от entrosity-axis.backend/api/openapi.yaml. Тази спецификация е първоизточникът: маршрутизаторът на сървъра и валидирането на заявките се генерират от нея, както и TypeScript типовете на портала, така че справочникът не може да се разминава с кода.

Конвенции

Базови пътища: портал /api/v1, агент /api/agent/v1, конектор /api/connector/v1 (последните два са описани в API за агента и конектора). Браузърите и новите скриптове достигат до него под пътя на Axis на хоста на Hub, https://hub.entrosity.com/axis/api/v1 (Caddy премахва /axis). По-старите адреси (/manage/api/v1 и /api/v1 на стария хост на Axis) продължават да работят за съществуващите скриптове (Кои стари адреси продължават да работят).
JSON тела с ключове в snake_case. Схемите на заявките отказват непознати полета (422).
Автентикация: Authorization: Bearer <product token>, петминутен токен от Entrosity Hub за продукта rmm (POST /api/platform/v1/auth/product-token, API на Hub). Axis няма собствени крайни точки за вход; потребителите, тенантите и ролите се управляват в Hub, а списъците с потребители и тенанти в Axis са само за четене.
Обхват по тенант: потребителите на тенант могат да извикват само /tenants/{their tenant id}/…; всеки друг идентификатор на тенант връща 404.
Списъци: ?page=1&page_size=50&sort=-last_seen_at&q=… → {"items": […], "page": 1, "page_size": 50, "total": 1234}. Максималната стойност на page_size е 200.
Идемпотентност: крайните точки POST, които създават задачи, приемат заглавка Idempotency-Key.
Всеки отговор съдържа X-Request-ID.
Ограничение на честотата на заявките: 20 заявки в секунда на IP адрес на клиента, пик 60 (RMM_API_RATE_PER_SECOND, RMM_API_RATE_BURST); телата на заявките са до 1 MB.

Грешки

Грешките са във формат RFC 7807 application/problem+json със стабилен code:

{
  "type": "/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "code": "validation",
  "detail": "validation failed",
  "fields": { "name": "minimum string length is 1" },
  "request_id": "…"
}

Всички кодове са изброени в Кодове на грешки.

Влизане от скрипт

Влезте в Hub веднъж (бисквитката за сесията се записва в cookie jar), след което получавайте продуктови токени от сесията, когато изтичат:

HUB=https://hub.entrosity.com
# 1. Sign in on the Hub (add "totp_code" when two-factor authentication is on)
curl -s -c jar -b jar "$HUB/api/platform/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"…"}'

# 2. A product token for Axis (valid 5 minutes; repeat when it expires)
TOKEN=$(curl -s -c jar -b jar "$HUB/api/platform/v1/auth/product-token" \
  -H 'Content-Type: application/json' -d '{"product":"rmm"}' | jq -r .token)

# 3. Call Axis's API
curl -s "$HUB/axis/api/v1/me" -H "Authorization: Bearer $TOKEN"

Hub ограничава честотата на влизанията, а не на продуктовите токени: запазете cookie jar файла и издайте нов токен, вместо да влизате отново.

Събития в реално време (SSE)

GET /tenants/{tenantID}/events е поток от събития, изпращани от сървъра (server-sent events), с промените в тенанта (състояние на устройства, задачи, напредък на внедрявания, изход от скриптове, аларми, AD синхронизация). Браузърите не могат да изпращат заглавки с EventSource, затова:

POST /auth/sse-token с {"tenant_id": "…"} връща 60-секунден токен за потока, обвързан с този тенант и вашата сесия в Hub (подписан от Axis с RMM_JWT_SECRET);
отворете /axis/api/v1/tenants/{tenantID}/events?sse_token=<token>.

Продуктовият токен никога не се приема в низа на заявката (query string).

Групи крайни точки

Група	Пътища
Проверка на състоянието	`/healthz`
Потоци от събития	`/auth/sse-token`
Текущ потребител	`/me` (потребителят с неговите тенанти и роли), `/tenants/{id}/me/notification-prefs`
Администриране	`/admin/overview`, `/admin/tenants` и `/admin/tenants/{id}` (списък, четене, `PATCH` само на `settings`), `/admin/users` (глобалните администратори, само за четене), `/admin/audit`, `/admin/packages…`, `/admin/winget/search`, `/admin/scripts…`, `/admin/alert-rules…`, `/admin/agent-releases…`
Тенант	`/tenants/{id}` (`PATCH` само на `settings`), `/dashboard`, `/users` (членовете и тяхната роля в Axis, само за четене), `/sites…`, `/audit`, `/events`, `/enrollment-tokens…` (изтриването изисква `step_up_token` от Hub)
Устройства	`/tenants/{id}/devices…` (списък, подробности, секции на инвентаризацията, метрики, задачи, действия, обединяване, групови действия), `/jobs/{jobID}`, `/jobs/{jobID}/cancel`
Active Directory	`/connectors…`, `/ad-sync/configs…`, `/ad-computers…`
Пакети и внедрявания	`/packages…`, `/winget/search`, `/deployments…`
Аларми	`/alerts`, `/alerts/acknowledge`, `/alerts/resolve`, `/alert-rules…`
Скриптове	`/scripts…`, `/script-runs…`

Кой какво може да извиква се определя за всеки маршрут в entrosity-axis.backend/internal/http/portal/access.go и е обобщено в Роли и права.

Промяна на API

Първо редактирайте entrosity-axis.backend/api/openapi.yaml.
make gen генерира отново интерфейса на Go сървъра и TypeScript типовете на портала; имплементирайте обработчика.
Добавете правилото за достъп на маршрута и ред в теста на RBAC матрицата.
make api-docs генерира отново docs/api/index.html. Този сайт показва спецификацията директно.
Актуализирайте тази документация (Писане на документация).

Конвенции​

Грешки​

Влизане от скрипт​

Събития в реално време (SSE)​

Групи крайни точки​

Промяна на API​