update docs

server/handler/auth.go

@@ -7,6 +7,8 @@ import (
 	"strings"
 	"time"
 	"vctp/internal/auth"
+	"vctp/server/audit"
+	"vctp/server/middleware"
 	"vctp/server/models"
 )
 
@@ -50,12 +52,14 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if h == nil || h.Settings == nil || h.Settings.Values == nil {
+		audit.LogAuthEvent(nil, r, "login", "error", "reason", "settings_not_configured")
 		writeJSONError(w, http.StatusInternalServerError, "authentication is not configured")
 		return
 	}
 
 	cfg := h.Settings.Values.Settings
 	if !cfg.AuthEnabled {
+		audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "auth_disabled")
 		writeJSONError(w, http.StatusServiceUnavailable, "authentication is disabled")
 		return
 	}
@@ -63,12 +67,14 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 	var req models.AuthLoginRequest
 	if err := decodeJSONBody(w, r, &req); err != nil {
 		h.Logger.Error("unable to decode auth login request", "error", err)
+		audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "invalid_request_json", "error", err)
 		writeJSONError(w, http.StatusBadRequest, "invalid JSON body")
 		return
 	}
 	username := strings.TrimSpace(req.Username)
 	password := req.Password
 	if username == "" || strings.TrimSpace(password) == "" {
+		audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "missing_username_or_password", "username", username)
 		writeJSONError(w, http.StatusBadRequest, "username and password are required")
 		return
 	}
@@ -83,6 +89,7 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 	})
 	if err != nil {
 		h.Logger.Error("failed to initialize ldap authenticator", "error", err)
+		audit.LogAuthEvent(h.Logger, r, "login", "error", "reason", "ldap_authenticator_init_failed", "username", username, "error", err)
 		writeJSONError(w, http.StatusInternalServerError, "authentication service unavailable")
 		return
 	}
@@ -92,23 +99,23 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 	identity, err := ldapAuth.AuthenticateAndFetchGroups(ctx, username, password)
 	if err != nil {
 		if errors.Is(err, auth.ErrLDAPInvalidCredentials) {
-			h.Logger.Warn("auth login rejected", "username", username, "reason", "invalid_credentials")
+			audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "invalid_credentials", "username", username)
 			writeJSONError(w, http.StatusUnauthorized, authLoginFailureMessage)
 			return
 		}
 		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
-			h.Logger.Warn("auth login ldap timeout", "username", username, "error", err)
+			audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "ldap_timeout", "username", username, "error", err)
 			writeJSONError(w, http.StatusUnauthorized, authLoginFailureMessage)
 			return
 		}
-		h.Logger.Warn("auth login ldap failure", "username", username, "error", err)
+		audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "ldap_authentication_failed", "username", username, "error", err)
 		writeJSONError(w, http.StatusUnauthorized, authLoginFailureMessage)
 		return
 	}
 
 	roles := auth.ResolveRoles(identity.Groups, cfg.AuthGroupRoleMappings)
 	if !auth.HasAnyGroup(identity.Groups, cfg.LDAPGroups) || len(roles) == 0 {
-		h.Logger.Warn("auth login rejected", "username", username, "reason", "group_or_role_denied")
+		audit.LogAuthEvent(h.Logger, r, "login", "deny", "reason", "group_or_role_denied", "username", username, "group_count", len(identity.Groups), "resolved_roles", roles)
 		writeJSONError(w, http.StatusUnauthorized, authLoginFailureMessage)
 		return
 	}
@@ -122,6 +129,7 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 	})
 	if err != nil {
 		h.Logger.Error("failed to initialize jwt service", "error", err)
+		audit.LogAuthEvent(h.Logger, r, "login", "error", "reason", "jwt_service_init_failed", "username", username, "error", err)
 		writeJSONError(w, http.StatusInternalServerError, "authentication service unavailable")
 		return
 	}
@@ -133,14 +141,53 @@ func (h *Handler) AuthLogin(w http.ResponseWriter, r *http.Request) {
 	token, claims, err := jwtSvc.IssueToken(subject, roles, identity.Groups)
 	if err != nil {
 		h.Logger.Error("failed to issue auth token", "username", username, "error", err)
+		audit.LogAuthEvent(h.Logger, r, "login", "error", "reason", "token_issue_failed", "username", username, "error", err)
 		writeJSONError(w, http.StatusInternalServerError, "failed to issue access token")
 		return
 	}
 
-	h.Logger.Info("auth login successful", "username", subject, "roles", roles)
+	audit.LogAuthEvent(h.Logger, r, "login", "allow", "username", subject, "resolved_roles", roles, "expires_at", claims.ExpiresAt)
 	writeJSON(w, http.StatusOK, models.AuthLoginResponse{
 		AccessToken: token,
 		ExpiresAt:   claims.ExpiresAt,
 		TokenType:   "Bearer",
 	})
 }
+
+// AuthMe returns the currently authenticated identity from validated JWT claims.
+// @Summary Who am I
+// @Description Returns JWT claims for the currently authenticated bearer token.
+// @Description Requires Bearer authentication.
+// @Tags auth
+// @Produce json
+// @Success 200 {object} models.AuthMeResponse "Authenticated identity"
+// @Failure 401 {object} models.ErrorResponse "Missing or invalid authentication context"
+// @Router /api/auth/me [get]
+// @Security BearerAuth
+func (h *Handler) AuthMe(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeJSONError(w, http.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+
+	claims, ok := middleware.ClaimsFromContext(r.Context())
+	if !ok {
+		audit.LogAuthEvent(h.Logger, r, "whoami", "deny", "reason", "missing_auth_context")
+		writeJSONError(w, http.StatusUnauthorized, "missing authentication context")
+		return
+	}
+
+	audit.LogAuthEvent(h.Logger, r, "whoami", "allow", "subject", claims.Subject, "roles", claims.Roles)
+	writeJSON(w, http.StatusOK, models.AuthMeResponse{
+		Status:    "OK",
+		Subject:   claims.Subject,
+		Roles:     claims.Roles,
+		Groups:    claims.Groups,
+		Issuer:    claims.Issuer,
+		Audience:  claims.Audience,
+		IssuedAt:  claims.IssuedAt,
+		ExpiresAt: claims.ExpiresAt,
+		NotBefore: claims.NotBefore,
+		TokenID:   claims.ID,
+	})
+}

server/handler/auth_test.go

@@ -12,6 +12,7 @@ import (
 	"time"
 	"vctp/internal/auth"
 	"vctp/internal/settings"
+	"vctp/server/middleware"
 	"vctp/server/models"
 )
 
@@ -187,6 +188,80 @@ func TestAuthLoginJWTFactoryFailure(t *testing.T) {
 	}
 }
 
+func TestAuthMeSuccess(t *testing.T) {
+	h := &Handler{
+		Logger:   newTestLogger(),
+		Settings: testAuthEnabledSettings(),
+	}
+	protected := middleware.RequireAuth(newTestLogger(), h.Settings)(http.HandlerFunc(h.AuthMe))
+
+	tokenSvc, err := auth.NewJWTService(auth.JWTConfig{
+		SigningKeyBase64: h.Settings.Values.Settings.AuthJWTSigningKey,
+		Issuer:           h.Settings.Values.Settings.AuthJWTIssuer,
+		Audience:         h.Settings.Values.Settings.AuthJWTAudience,
+		TokenLifespan:    time.Duration(h.Settings.Values.Settings.AuthTokenLifespanMinutes) * time.Minute,
+		ClockSkew:        time.Duration(h.Settings.Values.Settings.AuthClockSkewSeconds) * time.Second,
+	})
+	if err != nil {
+		t.Fatalf("failed to create jwt service: %v", err)
+	}
+	token, claims, err := tokenSvc.IssueToken("alice", []string{"viewer"}, []string{"cn=vctp-viewers,ou=groups,dc=example,dc=com"})
+	if err != nil {
+		t.Fatalf("failed to issue token: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/me", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rr := httptest.NewRecorder()
+	protected.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d: %s", http.StatusOK, rr.Code, rr.Body.String())
+	}
+	var payload models.AuthMeResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if payload.Status != "OK" {
+		t.Fatalf("unexpected status: %q", payload.Status)
+	}
+	if payload.Subject != claims.Subject {
+		t.Fatalf("unexpected subject: %q", payload.Subject)
+	}
+	if payload.Issuer != claims.Issuer || payload.Audience != claims.Audience {
+		t.Fatalf("unexpected issuer/audience: %q/%q", payload.Issuer, payload.Audience)
+	}
+	if payload.TokenID != claims.ID {
+		t.Fatalf("unexpected token id: %q", payload.TokenID)
+	}
+}
+
+func TestAuthMeMissingAuthContext(t *testing.T) {
+	h := &Handler{
+		Logger: newTestLogger(),
+	}
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/me", nil)
+	rr := httptest.NewRecorder()
+	h.AuthMe(rr, req)
+
+	if rr.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status %d, got %d", http.StatusUnauthorized, rr.Code)
+	}
+}
+
+func TestAuthMeMethodNotAllowed(t *testing.T) {
+	h := &Handler{
+		Logger: newTestLogger(),
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/me", nil)
+	rr := httptest.NewRecorder()
+	h.AuthMe(rr, req)
+
+	if rr.Code != http.StatusMethodNotAllowed {
+		t.Fatalf("expected status %d, got %d", http.StatusMethodNotAllowed, rr.Code)
+	}
+}
+
 func testAuthEnabledSettings() *settings.Settings {
 	cfg := &settings.Settings{Values: &settings.SettingsYML{}}
 	cfg.Values.Settings.AuthEnabled = true

server/handler/dailyCreationDiagnostics.go

@@ -13,6 +13,7 @@ import (
 // DailyCreationDiagnostics returns missing CreationTime diagnostics for a daily summary table.
 // @Summary Daily summary CreationTime diagnostics
 // @Description Returns counts of daily summary rows missing CreationTime and sample rows for the given date.
+// @Description Requires Bearer authentication with the viewer role (admin also allowed).
 // @Tags diagnostics
 // @Produce json
 // @Param date query string true "Daily date (YYYY-MM-DD)"
@@ -20,6 +21,7 @@ import (
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 404 {object} models.ErrorResponse "Summary not found"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/diagnostics/daily-creation [get]
 func (h *Handler) DailyCreationDiagnostics(w http.ResponseWriter, r *http.Request) {
 	dateValue := strings.TrimSpace(r.URL.Query().Get("date"))

server/handler/encryptData.go

@@ -17,6 +17,7 @@ type encryptRequest struct {
 // EncryptData encrypts a plaintext value and returns the ciphertext.
 // @Summary Encrypt data
 // @Description Encrypts a plaintext value and returns the ciphertext.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags crypto
 // @Accept json
 // @Produce json
@@ -24,6 +25,7 @@ type encryptRequest struct {
 // @Success 200 {object} models.StatusMessageResponse "Ciphertext response"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/encrypt [post]
 func (h *Handler) EncryptData(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/reportDownload.go

@@ -9,10 +9,12 @@ import (
 // InventoryReportDownload returns the inventory report as an XLSX download.
 // @Summary Download inventory report
 // @Description Generates an inventory XLSX report and returns it as a file download.
+// @Description Requires Bearer authentication with the viewer role (admin also allowed).
 // @Tags reports
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Success 200 {file} file "Inventory XLSX report"
 // @Failure 500 {object} models.ErrorResponse "Report generation failed"
+// @Security BearerAuth
 // @Router /api/report/inventory [get]
 func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := withRequestTimeout(r, reportRequestTimeout)
@@ -38,10 +40,12 @@ func (h *Handler) InventoryReportDownload(w http.ResponseWriter, r *http.Request
 // UpdateReportDownload returns the updates report as an XLSX download.
 // @Summary Download updates report
 // @Description Generates an updates XLSX report and returns it as a file download.
+// @Description Requires Bearer authentication with the viewer role (admin also allowed).
 // @Tags reports
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Success 200 {file} file "Updates XLSX report"
 // @Failure 500 {object} models.ErrorResponse "Report generation failed"
+// @Security BearerAuth
 // @Router /api/report/updates [get]
 func (h *Handler) UpdateReportDownload(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := withRequestTimeout(r, reportRequestTimeout)

server/handler/snapshotAggregate.go

@@ -11,6 +11,7 @@ import (
 // SnapshotAggregateForce forces regeneration of a daily or monthly summary table.
 // @Summary Force snapshot aggregation
 // @Description Forces regeneration of a daily or monthly summary table for a specified date or month.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Produce json
 // @Param type query string true "Aggregation type: daily or monthly"
@@ -19,6 +20,7 @@ import (
 // @Success 200 {object} models.StatusResponse "Aggregation complete"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/snapshots/aggregate [post]
 func (h *Handler) SnapshotAggregateForce(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshotForceHourly.go

@@ -10,6 +10,7 @@ import (
 // SnapshotForceHourly triggers an on-demand hourly snapshot run.
 // @Summary Trigger hourly snapshot (manual)
 // @Description Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Accept json
 // @Produce json
@@ -17,6 +18,7 @@ import (
 // @Success 200 {object} models.StatusResponse "Snapshot started"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/snapshots/hourly/force [post]
 func (h *Handler) SnapshotForceHourly(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshotMigrate.go

@@ -9,10 +9,12 @@ import (
 // SnapshotMigrate rebuilds the snapshot registry and normalizes hourly table names.
 // @Summary Migrate snapshot registry
 // @Description Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Produce json
 // @Success 200 {object} models.SnapshotMigrationResponse "Migration results"
 // @Failure 500 {object} models.SnapshotMigrationResponse "Server error"
+// @Security BearerAuth
 // @Router /api/snapshots/migrate [post]
 func (h *Handler) SnapshotMigrate(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshotRegenerateHourly.go

@@ -13,10 +13,12 @@ import (
 // SnapshotRegenerateHourlyReports regenerates missing hourly snapshot XLSX reports on disk.
 // @Summary Regenerate hourly snapshot reports
 // @Description Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Produce json
 // @Success 200 {object} models.SnapshotRegenerateReportsResponse "Regeneration summary"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/snapshots/regenerate-hourly-reports [post]
 func (h *Handler) SnapshotRegenerateHourlyReports(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshotRepair.go

@@ -15,9 +15,11 @@ import (
 // SnapshotRepair scans existing daily summaries and backfills missing SnapshotTime and lifecycle fields.
 // @Summary Repair daily summaries
 // @Description Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Produce json
 // @Success 200 {object} models.SnapshotRepairResponse
+// @Security BearerAuth
 // @Router /api/snapshots/repair [post]
 func (h *Handler) SnapshotRepair(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
@@ -98,9 +100,11 @@ func (h *Handler) repairDailySummaries(ctx context.Context, now time.Time) (repa
 // It rebuilds the snapshot registry, syncs vcenter totals, repairs daily summaries, and refines monthly lifecycle data.
 // @Summary Run full snapshot repair suite
 // @Description Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags snapshots
 // @Produce json
 // @Success 200 {object} models.SnapshotRepairSuiteResponse
+// @Security BearerAuth
 // @Router /api/snapshots/repair/all [post]
 func (h *Handler) SnapshotRepairSuite(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/snapshots.go

@@ -49,12 +49,14 @@ func (h *Handler) SnapshotMonthlyList(w http.ResponseWriter, r *http.Request) {
 // SnapshotReportDownload streams a snapshot table as XLSX.
 // @Summary Download snapshot report
 // @Description Downloads a snapshot table as an XLSX file.
+// @Description Requires Bearer authentication with the viewer role (admin also allowed).
 // @Tags snapshots
 // @Produce application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 // @Param table query string true "Snapshot table name"
 // @Success 200 {file} file "Snapshot XLSX report"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/report/snapshot [get]
 func (h *Handler) SnapshotReportDownload(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := withRequestTimeout(r, reportRequestTimeout)

server/handler/updateCleanup.go

@@ -8,11 +8,13 @@ import (
 // UpdateCleanup removes orphaned update records.
 // @Summary Cleanup updates (deprecated)
 // @Description Deprecated: Removes update records that are no longer associated with a VM.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags maintenance
 // @Deprecated
 // @Produce text/plain
 // @Success 200 {string} string "Cleanup completed"
 // @Failure 500 {string} string "Server error"
+// @Security BearerAuth
 // @Router /api/cleanup/updates [delete]
 func (h *Handler) UpdateCleanup(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodDelete {

server/handler/vcenterCacheRebuild.go

@@ -15,6 +15,7 @@ import (
 // VcenterCacheRebuild force-regenerates cached vCenter reference data in the database.
 // @Summary Rebuild vCenter object cache
 // @Description Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags vcenters
 // @Produce json
 // @Param vcenter query string false "Optional single vCenter URL to rebuild; defaults to all configured vCenters"
@@ -22,6 +23,7 @@ import (
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 405 {object} models.ErrorResponse "Method not allowed"
 // @Failure 500 {object} models.VcenterCacheRebuildResponse "All rebuild attempts failed"
+// @Security BearerAuth
 // @Router /api/vcenters/cache/rebuild [post]
 func (h *Handler) VcenterCacheRebuild(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmCleanup.go

@@ -11,6 +11,7 @@ import (
 // VmCleanup removes a VM from inventory by ID and datacenter.
 // @Summary Cleanup VM inventory entry (deprecated)
 // @Description Deprecated: Removes a VM inventory entry by VM ID and datacenter name.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags inventory
 // @Deprecated
 // @Produce json
@@ -18,6 +19,7 @@ import (
 // @Param datacenter_name query string true "Datacenter name"
 // @Success 200 {object} models.StatusMessageResponse "Cleanup completed"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
+// @Security BearerAuth
 // @Router /api/inventory/vm/delete [delete]
 func (h *Handler) VmCleanup(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodDelete {

server/handler/vmCreateEvent.go

@@ -15,6 +15,7 @@ import (
 // VmCreateEvent records a VM creation CloudEvent.
 // @Summary Record VM create event (deprecated)
 // @Description Deprecated: Parses a VM create CloudEvent and stores the event data.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags events
 // @Deprecated
 // @Accept json
@@ -23,6 +24,7 @@ import (
 // @Success 200 {object} models.StatusMessageResponse "Create event processed"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/event/vm/create [post]
 func (h *Handler) VmCreateEvent(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmDeleteEvent.go

@@ -12,6 +12,7 @@ import (
 // VmDeleteEvent records a VM deletion CloudEvent in the inventory.
 // @Summary Record VM delete event (deprecated)
 // @Description Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags events
 // @Deprecated
 // @Accept json
@@ -20,6 +21,7 @@ import (
 // @Success 200 {object} models.StatusMessageResponse "Delete event processed"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/event/vm/delete [post]
 func (h *Handler) VmDeleteEvent(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmImport.go

@@ -14,6 +14,7 @@ import (
 // VmImport ingests a bulk VM import payload.
 // @Summary Import VMs (deprecated)
 // @Description Deprecated: Imports existing VM inventory data in bulk.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags inventory
 // @Deprecated
 // @Accept json
@@ -21,6 +22,7 @@ import (
 // @Param import body models.ImportReceived true "Bulk import payload"
 // @Success 200 {object} models.StatusMessageResponse "Import processed"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/import/vm [post]
 func (h *Handler) VmImport(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmModifyEvent.go

@@ -21,6 +21,7 @@ import (
 // VmModifyEvent records a VM modification CloudEvent.
 // @Summary Record VM modify event (deprecated)
 // @Description Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags events
 // @Deprecated
 // @Accept json
@@ -29,6 +30,7 @@ import (
 // @Success 200 {object} models.StatusMessageResponse "Modify event processed"
 // @Success 202 {object} models.StatusMessageResponse "No relevant changes"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/event/vm/modify [post]
 func (h *Handler) VmModifyEvent(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmMoveEvent.go

@@ -14,6 +14,7 @@ import (
 // VmMoveEvent records a VM move CloudEvent as an update.
 // @Summary Record VM move event (deprecated)
 // @Description Deprecated: Parses a VM move CloudEvent and creates an update record.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags events
 // @Deprecated
 // @Accept json
@@ -22,6 +23,7 @@ import (
 // @Success 200 {object} models.StatusMessageResponse "Move event processed"
 // @Failure 400 {object} models.ErrorResponse "Invalid request"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/event/vm/move [post]
 func (h *Handler) VmMoveEvent(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {

server/handler/vmUpdateDetails.go

@@ -12,11 +12,13 @@ import (
 // VmUpdateDetails refreshes inventory metadata from vCenter.
 // @Summary Refresh VM details (deprecated)
 // @Description Deprecated: Queries vCenter and updates inventory records with missing details.
+// @Description Requires Bearer authentication with the admin role.
 // @Tags inventory
 // @Deprecated
 // @Produce json
 // @Success 200 {object} models.StatusMessageResponse "Update completed"
 // @Failure 500 {object} models.ErrorResponse "Server error"
+// @Security BearerAuth
 // @Router /api/inventory/vm/update [post]
 func (h *Handler) VmUpdateDetails(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {