API на Hub

Уеб приложението на Entrosity Hub е обикновен клиент на REST API под /api/platform/v1. Пълният справочник на крайните точки (endpoints) е справочникът за API на Hub, генериран от entrosity-hub.backend/api/openapi.yaml – спецификацията, от която се генерират маршрутизаторът и валидирането на заявките в Hub.

Конвенции

• JSON тела с ключове в snake_case; схемите на заявките отхвърлят непознати полета (422). Грешките са problem документи с code (Кодове на грешки).
• Сесия: POST /auth/login задава бисквитката на сесията platform_rt (HttpOnly, SameSite=Strict, път /api/platform/v1/auth, 30 дни, ротира се при всяко опресняване с откриване на повторна употреба) и връща токен за достъп с валидност 15 минути за собственото API на Hub (Authorization: Bearer, аудитория platform).
• Маршрути с бисквитка (/auth/refresh, /auth/logout, /auth/product-token, /auth/step-up) приемат само заявки от собствения произход (origin) на Hub: Sec-Fetch-Site на браузъра трябва да е same-origin или неговият Origin да е този на Hub (PLATFORM_PUBLIC_URL). Съседни хостове от същия сайт се отказват.
• Достъп: всеки маршрут има правило в entrosity-hub.backend/internal/http/api/access.go: публичен, бисквитка на сесията, влязъл потребител, администратор на организацията (маршрутите на организация отговарят с 404 на всеки, който не е администратор на тази организация или администратор на платформата) или администратор на платформата (403 в противен случай).
• Списъците със страниране приемат ?page=&page_size= и връщат items, page, page_size и total.

Токени за продуктите

Продуктите никога не виждат бисквитката на сесията. Техните уеб приложения, обслужвани от същия хост, искат с нея краткотрайни токени от Hub:

Извикване	Токен	Валидност
POST /auth/product-token {product}	Токен за достъп до продукт: aud = идентификаторът на продукта (rmm), sub = потребител, sid = сесия, email, name. Без роли: продуктите ги четат от своето копие на данните на Hub. 403 no_product_access без роля в продукта, 403 totp_setup_required, когато организацията изисква двуфакторна автентикация и тя не е настроена.	5 минути
POST /auth/step-up {product, password}	Токен за допълнително потвърждение (step-up) за едно чувствително действие (purpose: step-up, еднократен jti, обвързан с потребителя и сесията). Грешна парола е 422 за password; ограничение на честотата на заявките както при влизане.	2 минути

И двете извиквания само четат сесията (никога не ротират бисквитката), затова могат да се изпълняват, докато друг раздел я опреснява. Токените са Ed25519 JWT (alg: EdDSA) с издател PLATFORM_PUBLIC_URL и заглавка kid; публичните ключове се публикуват на GET /api/platform/v1/.well-known/jwks.json и на вътрешния слушател.

Вътрешно API

Втори слушател (PLATFORM_INTERNAL_ADDR) обслужва продуктите по частната мрежа; Caddy никога не насочва трафик към него.

Маршрут	Автентикация	Връща
GET /internal/v1/jwks.json	няма	Ключовете за подписване (текущият и, по време на ротация, предишният).
GET /internal/v1/products/{product}/snapshot	Authorization: Bearer <product token> от PLATFORM_PRODUCT_TOKENS (сравнение с постоянно време)	Всичко, от което продуктът се нуждае за оторизация: потребителите с роля в продукта и администраторите на платформата (с всякакво състояние), организациите с активиран продукт, ролите на продукта и сесиите, приключили през последните 15 минути. ETag / If-None-Match връщат 304, когато нищо не се е променило.

Axis изтегля моментната снимка (snapshot) на всеки RMM_PLATFORM_SYNC_INTERVAL (Архитектура).