Vertex API

Всичко, което прави Entrosity Vertex, е достъпно чрез REST API под /api/v1; уеб интерфейсът на Vertex, който е в разработка, ще бъде обикновен клиент на него. Пълният справочник на крайните точки е справочникът на Vertex API, генериран от entrosity-vertex.backend/api/openapi.yaml – спецификацията, от която се генерират маршрутизаторът и валидирането на заявките на сървъра.

Конвенции

Базов URL: https://hub.entrosity.com/vertex/api/v1, след като Vertex бъде внедрен (проксито премахва /vertex; Работа с Entrosity Vertex).
Удостоверяване: Authorization: Bearer <product token>, петминутен токен от Entrosity Hub за продукта vertex (POST /api/platform/v1/auth/product-token {"product":"vertex"} със сесията на Hub, Hub API). Vertex няма собствено влизане; потребителите, тенантите и ролите идват от Hub. Докато Vertex е в бета версия, Hub издава токените му само на администратори на платформата.
Правила за достъп: всеки маршрут има правило в entrosity-vertex.backend/internal/http/portal/access.go: публичен, влязъл потребител, глобален администратор или право в тенанта (Роли и права). Потребителите на тенант могат да извикват само /tenants/{идентификатор на техния тенант}/…; всеки друг тенант отговаря с 404. Липсващо право отговаря с 403 forbidden. Маршрутите за обекти (/objects/{objectID}, членство, групови действия) са с най-слабото право, а обработчикът проверява правото, нужно на операцията (directory.RequiredPermission): например Helpdesk може да изпрати PATCH за атрибутите за контакт на потребител, но за нищо друго.
JSON тела с ключове в snake_case. Схемите на заявките отказват непознати полета (422).
Обектите се адресират с техния objectGUID (objectID), а GPO – с техния GUID (gpoID); отличителните имена се появяват в телата (ou, target_ou, DN на групи и членове).
Атрибутите са речници от LDAP имена към масиви от низове; двоичните стойности са b64:<base64> (Потребители → Промяна на атрибути).
Списъците приемат ?page=&page_size= (по подразбиране 50, най-много 500) и връщат items, page, page_size и total; списъците с OU, GPO и политики за пароли връщат всички елементи.
Ограничения на честотата: 20 заявки в секунда на клиентски IP, пик 60 (VERTEX_API_RATE_PER_SECOND, VERTEX_API_RATE_BURST). Промените се броят и към 600 на потребител и 2000 на тенант в минута (429 rate_limited).
Всеки отговор носи X-Request-ID.

Грешки

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

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "writes_disabled",
  "detail": "gpo changes are switched off in the directory settings",
  "request_id": "…"
}

Грешките при валидиране имат code: "validation" и fields със съобщение за всяко поле. Всички кодове и какво да направите при тях: Отстраняване на проблеми с Vertex.

Операции

Четенето на списъци и обекти идва от огледалото на Vertex и отговаря веднага. Всичко, което достига до Active Directory (промени, тестът, синхронизациите, четенето на живо, отчетите и резервните копия на GPO), е операция и отговаря с 202 и нея:

POST /tenants/{tenantID}/users/{objectID}/password
{"password": "…", "must_change": true, "unlock": true}

{ "id": "0192…", "op": "user.password", "class": "user", "is_delete": false,
  "target_kind": "user", "target_id": "3f1c…", "target_dn": "CN=Ivan Petrov,OU=Students,…",
  "summary": "Reset the password of ipetrov", "status": "queued", … }

Крайните точки, които действат върху няколко групи или потребители (…/users/{objectID}/groups, …/users/bulk-actions), отговарят с 202 и {items: [Operation…]}.

Следене на операция:

GET /tenants/{tenantID}/operations/{operationID}?wait=20 отговаря веднага щом тя приключи или след wait секунди (от 0 до 25);
или събитието vertex.operation от потока на живо.

status минава pending → queued → running → succeeded, failed, cancelled или timeout, с progress_pct и progress_message за дългите. Неуспешната операция има error_code и error. result съдържа това, което е върнал конекторът: промененият object (с всичките му атрибути), gpo, изтритият GUID в deleted, backup_id на GPO, резултатът от test или counts. params повтаря заявката, никога с пароли.

POST …/operations/{operationID}/cancel отменя операция, която не е приключила (доколкото е възможно, ако вече се изпълнява; иначе 409 operation_finished). GET …/operations ги изброява от най-новата, с филтри по target_id, status, class (read, user, group, ou, gpo, pso) и changes_only.

Потвърждение с парола

Запазването на настройките на директорията (step_up_token в тялото), изтриванията (заглавка X-Step-Up-Token при DELETE …/objects/{objectID} и DELETE …/gpos/{gpoID}; step_up_token при групово delete) и прилагането на импорт (step_up_token) изискват токен за потвърждение от Hub за паролата на извикващия (POST /api/platform/v1/auth/step-up, продукт vertex). Всеки токен се използва веднъж; без такъв отговорът е 403 step_up_required.

Тайни

Паролата на AD акаунта (ad_password в настройките) и паролите на нови потребители, смените на пароли и импортите са само за запис: никоя крайна точка не ги връща, операциите и одитният журнал никога не ги съдържат и те се пазят криптирани (VERTEX_CREDENTIALS_KEY) само докато конекторът ги вземе. Вместо това настройките връщат has_password.

Импорти

POST /tenants/{tenantID}/imports {csv, filename, mode, options} (201) валидира CSV файл в преглед; GET …/imports/{importID}/rows показва всеки ред; POST …/commit {step_up_token} го прилага; POST …/cancel го изхвърля; GET …/result.csv връща резултата; GET …/imports/template – пример. Формат и правила: Групов импорт.

Обновления на живо

GET /tenants/{tenantID}/stream е text/event-stream. Браузърите се удостоверяват с ?sse_token= от POST /auth/sse-token {"tenant_id": "…"} (валиден 60 секунди; пази токена за достъп извън URL адресите). Събития:

Събитие	Данни	Значение
`vertex.operation`	`{id, op, status, progress_pct?, progress_message?, target_id?, error_code?}`	Операция е поставена в опашката, напреднала е или е приключила.
`vertex.directory`	`{kinds: […]}`	Огледалото се е променило за тези видове (`user`, `group`, `ou`, `pso`, `gpo`): заредете ги отново.
`vertex.import`	`{import_id}`	Редовете или броячите на импорт са се променили.
`vertex.settings`	`{}`	Настройките на директорията са се променили.

Вътрешно API (Entrosity Axis)

Vertex достига до конекторите през Axis, а Axis препраща обратно заявките за тайни и резултатите на конекторите, по два вътрешни слушателя, които никога не се публикуват и споделят един bearer токен (VERTEX_AXIS_TOKEN = RMM_VERTEX_AXIS_TOKEN на Axis). Крайни точки и правила: Протокол на Vertex → Мостът.

Конвенции​

Грешки​

Операции​

Потвърждение с парола​

Тайни​

Импорти​

Обновления на живо​

Вътрешно API (Entrosity Axis)​