API overview¶

Обновлено: 2026-05-30
Base URL: https://scope.kz/api (через nginx) или http://<host>:8080/api (backend напрямую)
Auth: Bearer JWT после /api/auth/login + /api/auth/2fa/verify.

Полная спецификация¶

Ресурс	Ссылка
OpenAPI JSON	openapi.json
Интерактивный ReDoc	openapi-spec.md
Таблица всех endpoints	api-endpoints.md (auto-generated)
Swagger UI (lab)	`http://10.0.9.111:8080/docs`

Экспорт: ./infra/scripts/docs-export-openapi.sh

Auth¶

Method	Path	Описание
POST	`/api/auth/login`	Email + password → 2FA challenge / tokens
POST	`/api/auth/2fa/verify`	TOTP → JWT
POST	`/api/auth/refresh`	Refresh access token
GET	`/api/auth/me`	Текущий пользователь
GET	`/api/auth/session`	Сессия / claims
POST	`/api/auth/logout`	Logout
POST	`/api/auth/change-password`	Смена пароля

Resources (servers)¶

Method	Path	Min role
GET	`/api/resources`	authenticated (list scoped by role)
POST	`/api/resources`	admin
GET/PATCH/DELETE	`/api/resources/{resource_id}`	admin
POST	`/api/resources/{resource_id}/test`	admin
GET	`/api/resources/readiness`	admin
GET	`/api/resources/{resource_id}/readiness`	admin
GET	`/api/resources/{resource_id}/metrics`	admin

Groups¶

Method	Path	Min role
GET/POST	`/api/groups`	admin
PATCH/DELETE	`/api/groups/{group_id}`	admin

Discovery (AD)¶

Method	Path	Min role
GET	`/api/discovery/computers`	admin
POST	`/api/discovery/import`	admin
GET	`/api/discovery/setup-script`	admin

Permissions (grants)¶

Method	Path	Min role
GET	`/api/resources/permissions`	admin
POST	`/api/resources/permissions`	super_admin
DELETE	`/api/resources/permissions/{permission_id}`	super_admin

Sessions¶

Method	Path	Min role
POST	`/api/sessions`	authenticated (connect gate)
GET	`/api/sessions/active`	admin / super_admin
GET	`/api/sessions/{session_id}`	owner or admin+
POST	`/api/sessions/{session_id}/disconnect`	owner or admin+

WebSocket (prefix /ws, не /api):

Path	Протокол
`/ws/session/{token}`	RDP / VNC
`/ws/ssh/{token}`	SSH terminal

Access requests (JIT)¶

Method	Path	Min role
GET/POST	`/api/access-requests`	authenticated
GET	`/api/access-requests/catalog`	authenticated
GET	`/api/access-requests/pending-count`	super_admin
POST	`/api/access-requests/{request_id}/approve`	super_admin
POST	`/api/access-requests/{request_id}/deny`	super_admin
POST	`/api/access-requests/{request_id}/cancel`	owner (pending)

SFTP & files¶

Prefix	Описание
`/api/resources/{resource_id}/sftp/*`	list, mkdir, upload, download, rename, delete
`/api/sftp/transfer`	server-to-server transfer
`/api/resources/{resource_id}/winrm/files/*`	RDP file pane (WinRM)

Audit¶

Method	Path	Min role
GET	`/api/audit/logs`	super_admin
GET	`/api/audit/logs/export`	super_admin
GET/POST	`/api/audit/screenshots`	session / super_admin
DELETE	`/api/audit/screenshots/{screenshot_id}`	super_admin
GET/DELETE	`/api/audit/recordings/{recording_id}`	super_admin

Users¶

Method	Path	Min role
GET/POST	`/api/users`	admin (UI Users: super_admin)
GET/PATCH	`/api/users/{user_id}`	admin
GET	`/api/users/active`	admin
GET	`/api/users/{user_id}/access`	admin

Profile (self-service)¶

Method	Path	Описание
GET/PATCH	`/api/profile`	Профиль
GET/PUT/DELETE	`/api/profile/domain-credentials`	Domain passwords (RDP reuse)
GET	`/api/profile/activity`	Свой audit trail
GET	`/api/profile/sessions`	Свои сессии
POST	`/api/profile/sessions/{session_id}/disconnect`	Disconnect своей сессии

Dashboard & metrics¶

Method	Path	Min role
GET	`/api/dashboard/overview`	admin
GET	`/api/dashboard/activity`	admin
GET	`/api/dashboard/host-metrics`	admin
GET	`/api/metrics/latest`	admin
GET	`/api/metrics/history`	admin

Alerts¶

Method	Path	Min role
GET	`/api/alerts`	admin
GET	`/api/alerts/counts`	admin
POST	`/api/alerts/{alert_id}/ack`	admin
POST	`/api/alerts/{alert_id}/resolve`	admin
GET/POST/PATCH/DELETE	`/api/alert-rules`	admin

Settings¶

Method	Path	Min role
GET/PATCH	`/api/settings/session`	admin
GET/PATCH	`/api/settings/retention`	super_admin
GET/PATCH	`/api/settings/ldap`	super_admin
POST	`/api/settings/ldap/test`	super_admin
POST	`/api/settings/purge/*`	super_admin

AI assistant¶

Method	Path	Min role
GET	`/api/ai/status`	authenticated
GET/PATCH	`/api/ai/config`	super_admin
POST	`/api/ai/chat`	authenticated (if enabled)

Health (no auth)¶

Method	Path
GET	`/health/live`
GET	`/health/ready`

Источник ролей: rbac-matrix.md.