openapi.yaml

openapi: 3.0.3
info:
  title: My Nethesis API
  description: REST API for My Nethesis with business hierarchy management and RBAC
  version: 0.6.1
  contact:
    name: Nethesis S.r.l.
    url: http://www.nethesis.it
    email: info@nethesis.it
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.html

servers:
  - url: https://api.your-domain.com/api
    description: Backend API server (port 8080)
  - url: https://collect.your-domain.com/api
    description: Collect API server (port 8081)

tags:

  - name: Backend - Authentication
    description: Token exchange, refresh, and logout
  - name: Backend - Me
    description: Current user profile, password and avatar management
  - name: Backend - Impersonation
    description: Consent-based user impersonation flow (start, exit, status, consent)
  - name: Backend - Impersonation Sessions
    description: Impersonation session history and audit logs

  - name: Backend - Users
    description: User CRUD and lifecycle management
  - name: Backend - Users Stats
    description: User statistics and trends
  - name: Backend - Users Import/Export
    description: User CSV import and CSV/PDF export

  - name: Backend - Distributors
    description: Distributor CRUD and lifecycle management
  - name: Backend - Distributors Stats
    description: Distributor statistics and trends
  - name: Backend - Distributors Import/Export
    description: Distributor CSV import and CSV/PDF export

  - name: Backend - Resellers
    description: Reseller CRUD and lifecycle management
  - name: Backend - Resellers Stats
    description: Reseller statistics and trends
  - name: Backend - Resellers Import/Export
    description: Reseller CSV import and CSV/PDF export

  - name: Backend - Customers
    description: Customer CRUD and lifecycle management
  - name: Backend - Customers Stats
    description: Customer statistics and trends
  - name: Backend - Customers Import/Export
    description: Customer CSV import and CSV/PDF export

  - name: Backend - Systems
    description: System CRUD and lifecycle management
  - name: Backend - Systems Stats
    description: System statistics, trends and exports
  - name: Backend - Systems Inventory
    description: System inventory history, diffs and timeline

  - name: Backend - Applications
    description: Application CRUD and organization assignment
  - name: Backend - Applications Stats
    description: Application statistics, summaries and trends

  - name: Backend - Metadata
    description: Read-only reference data (roles, organization roles, organizations, third-party applications)
  - name: Backend - Filters
    description: Aggregated filter values for UI dropdowns

  - name: Backend - Rebranding
    description: Rebranding management for organizations and products

  - name: Backend - Public
    description: Public endpoints requiring no authentication (avatars, etc.)
  - name: Backend - User
    description: OAuth2/OIDC user profile and permissions endpoints
  - name: Backend - Validators
    description: Real-time validation endpoints (VAT, etc.)
  - name: Backend - Health
    description: Backend service health check

  - name: Backend - Alerts
    description: Active alert monitoring and aggregates (list, totals, trend, stats, history, activity)
  - name: Backend - Alerts Configuration
    description: Per-organization alerting layer configuration and effective merged config
  - name: Backend - Alerts Silences
    description: Cross-hierarchy alert silences (mute/unmute across systems)
  - name: Backend - Alerts (Per-System)
    description: Alerts and silences scoped to a single system (/systems/{id}/alerts)

  - name: Collect - Health
    description: Collect service health and monitoring
  - name: Collect - Systems
    description: Collect service inventory and heartbeat collection
  - name: Collect - Rebranding
    description: Collect service rebranding endpoints for systems
  - name: Collect - Alerting
    description: |
      Collect service alerting proxy to Mimir Alertmanager.
      
      **Multi-tenant Alertmanager API**
      
      This proxy forwards requests to the Grafana Mimir Alertmanager with automatic multi-tenant isolation.
      Each system's organization is automatically resolved and injected as the `X-Scope-OrgID` header,
      ensuring complete isolation of alerts and silences between organizations.
      
      **Accessible endpoints:**
      - `POST /api/services/mimir/alertmanager/api/v2/alerts` - Push alerts
      - `GET /api/services/mimir/alertmanager/api/v2/alerts` - List alerts
      - `POST /api/services/mimir/alertmanager/api/v2/silences` - Create silence
      - `GET /api/services/mimir/alertmanager/api/v2/silences` - List silences
      - `GET /api/services/mimir/alertmanager/api/v2/silences/{id}` - Get silence
      - `DELETE /api/services/mimir/alertmanager/api/v2/silences/{id}` - Delete silence
      - `POST /api/alert_history` - Alertmanager webhook for alert history persistence
security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from auth exchange endpoint
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication for system inventory collection

  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: HTTP error code
          example: 400
        message:
          type: string
          description: Error message
          example: "validation failed"
        data:
          $ref: '#/components/schemas/ErrorData'

    ChannelToggles:
      type: object
      description: |
        Per-layer enable/disable for each notification channel. Each value
        is tri-state:
          * `true`  — explicitly enabled at this layer
          * `false` — explicitly disabled (Owner only; non-Owner false is
                     normalised to null on save)
          * `null`  — no opinion at this layer; effective state inherits
                     from the merge of any ancestor layer that took a
                     position. If no layer in the chain enables a channel,
                     the channel stays off.
      properties:
        email:
          type: boolean
          nullable: true
        webhook:
          type: boolean
          nullable: true
        telegram:
          type: boolean
          nullable: true
    EmailRecipient:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          format: email
          maxLength: 320
        severities:
          type: array
          maxItems: 3
          items:
            type: string
            enum: [critical, warning, info]
          description: |
            Severity scope for this recipient. Empty (or omitted) means
            "all severities" — the recipient lands on every per-severity
            receiver. A non-empty subset narrows delivery to those severities.
        language:
          type: string
          enum: [en, it]
          description: |
            Rendering language for this recipient's email body and subject.
            Defaults to `en` when omitted.
        format:
          type: string
          enum: [html, plain]
          description: |
            Body format preference. `html` (default) emits multipart with
            an html primary body and text alternative; `plain` emits only
            a text body.
    WebhookRecipient:
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
          maxLength: 100
          description: Descriptive label for the webhook target (UI only).
        url:
          type: string
          format: uri
          maxLength: 2048
          description: |
            Webhook URL. Validation rejects non-public destinations (loopback,
            RFC1918, RFC6598 CGNAT, link-local, multicast, cloud metadata) and
            requires a canonical hostname (containing at least one letter) or
            a valid IP literal. Only http/https schemes are accepted; URLs
            cannot embed userinfo.
        severities:
          type: array
          maxItems: 3
          items:
            type: string
            enum: [critical, warning, info]
    TelegramRecipient:
      type: object
      required:
        - bot_token
        - chat_id
      properties:
        bot_token:
          type: string
          maxLength: 256
          example: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
        chat_id:
          type: integer
          format: int64
          example: -1001234567890
        severities:
          type: array
          maxItems: 3
          items:
            type: string
            enum: [critical, warning, info]
    AlertmanagerSilenceStatus:
      type: object
      properties:
        state:
          type: string
          enum: [active, expired, pending]
          description: Runtime state of the silence
          example: "active"

    AlertmanagerMatcher:
      type: object
      properties:
        name:
          type: string
          description: Label name
          example: "alertname"
        value:
          type: string
          description: Label value
          example: "HighCPU"
        isRegex:
          type: boolean
          description: Whether the value is a regex
          example: false

    AlertmanagerSilence:
      type: object
      properties:
        id:
          type: string
          description: Alertmanager silence ID
          example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
        matchers:
          type: array
          items:
            $ref: '#/components/schemas/AlertmanagerMatcher'
        startsAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        endsAt:
          type: string
          format: date-time
          example: "2024-01-01T01:00:00Z"
        updatedAt:
          type: string
          format: date-time
          example: "2024-01-01T00:00:00Z"
        createdBy:
          type: string
          example: "admin@example.com"
        comment:
          type: string
          example: "silenced during maintenance"
        status:
          $ref: '#/components/schemas/AlertmanagerSilenceStatus'

    AlertingConfigLayer:
      type: object
      description: |
        The caller's alerting configuration. This is what POST /alerts/config
        accepts and what GET /alerts/config returns; the merged effective
        config that backs Mimir is computed server-side and never exposed.

        Each recipient carries its own `severities[]` (empty = all
        severities); email recipients additionally carry per-recipient
        `language` and `format`. Channel toggles under `enabled` are
        tri-state: null = no opinion at this layer (inherit), true =
        enabled, false = disabled (Owner only — non-Owner false is
        normalised to null on save).

        Body size: the request body is capped at 1 MiB on POST. Oversized
        requests are rejected with HTTP 413 before binding.
      properties:
        enabled:
          $ref: '#/components/schemas/ChannelToggles'
        email_recipients:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/EmailRecipient'
        webhook_recipients:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/WebhookRecipient'
        telegram_recipients:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/TelegramRecipient'

    ErrorData:
      type: object
      properties:
        type:
          type: string
          enum: [validation_error, external_api_error]
          description: Type of error
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
        details:
          description: Additional error details

    ValidationError:
      type: object
      properties:
        key:
          type: string
          description: Field name that failed validation
          example: "username"
        message:
          type: string
          description: Error code or message
          example: "required"
        value:
          type: string
          description: Value that failed validation
          example: ""

    VATValidationResponse:
      type: object
      properties:
        exists:
          type: boolean
          description: Whether the VAT number exists in the specified entity type
          example: true

    ActiveAlert:
      type: object
      description: |
        Active alert returned by Mimir Alertmanager. The fan-out includes
        silenced and inhibited alerts (not just `active` ones), so callers can
        render the muted/suppressed state. System identity (id, key, name,
        type) is carried as labels (`system_id`, `system_key`, `system_name`,
        `system_type`), stamped server-side at ingest time.
      properties:
        fingerprint:
          type: string
          description: Alertmanager fingerprint (hex hash of labels)
          example: "01cfde4b7fa6d1c7"
        labels:
          type: object
          additionalProperties:
            type: string
          description: |
            Alert labels. Always includes server-stamped identity labels
            (`system_id`, `system_key`, `system_name`, `system_type`,
            `system_fqdn`, `system_ipv4`, `organization_id`,
            `organization_name`, `organization_vat`, `organization_type`)
            plus the alert's own labels (`alertname`, `severity`, ...). Use
            `system_id` to link to the system detail page (/systems/:id) and
            `organization_id` to link to the organization.
          example:
            alertname: "DiskFilling"
            severity: "warning"
            system_id: "35aa0d84-08c1-4013-b1fd-d5f6ef3e0541"
            system_key: "NETH-FBB2-1A6E-7CAD-44A4-A772-B3EE-F0F6-F371"
            system_name: "cust1-sys-A"
            system_type: "ns8"
            organization_id: "org-1a2b3c4d"
            organization_name: "Test Customer"
            organization_type: "customer"
            organization_vat: "123456789012"
        annotations:
          type: object
          additionalProperties:
            type: string
        status:
          type: object
          properties:
            state:
              type: string
              enum: [active, suppressed, unprocessed]
            silencedBy:
              type: array
              items:
                type: string
              description: Active silence IDs muting this alert (non-empty → state is "suppressed")
            inhibitedBy:
              type: array
              items:
                type: string
        startsAt:
          type: string
          format: date-time
        endsAt:
          type: string
          format: date-time
        generatorURL:
          type: string
          description: Source URL of the alert (set by the pushing agent), if any

    AlertActivityEntry:
      type: object
      description: One event in the per-alert audit timeline (silence created/updated/removed).
      properties:
        id:
          type: integer
          format: int64
        organization_id:
          type: string
        fingerprint:
          type: string
          description: Alertmanager fingerprint of the alert this event belongs to
        action:
          type: string
          enum: [silenced, silence_updated, unsilenced]
          description: Event kind. Note edits are surfaced as `silence_updated` (note = silence comment).
        actor_user_id:
          type: string
          nullable: true
          description: logto_id of the user who triggered the action
        actor_name:
          type: string
          nullable: true
          description: Display name of the actor (denormalized for cheap render)
        silence_id:
          type: string
          nullable: true
          description: Silence ID associated with this event
        details:
          type: object
          additionalProperties: true
          description: |
            Free-form payload for the event. For `silenced` / `silence_updated`:
            `{comment, end_at, duration_minutes?}`. For `unsilenced`: empty.
        created_at:
          type: string
          format: date-time

    AlertHistoryRecord:
      type: object
      description: A single resolved or inactive alert stored from an Alertmanager webhook
      properties:
        id:
          type: integer
          format: int64
          description: Auto-incrementing record ID
          example: 1
        organization_id:
          type: string
          description: Tenant the alert belongs to (logto_id of the owning org)
          example: "m4m3mdjdiizs"
        system_key:
          type: string
          description: System key extracted from alert labels
          example: "NETH-F5D2-5E69-A174-45A9-B1AB-2BB9-03F5-F1B4"
        alertname:
          type: string
          description: Alert name from labels
          example: "DiskFull"
        severity:
          type: string
          nullable: true
          description: Severity from alert labels
          example: "critical"
        status:
          type: string
          description: Alert status at time of receipt
          enum: [resolved, inactive]
          example: "resolved"
        fingerprint:
          type: string
          description: Alertmanager fingerprint for the alert
          example: "ac193fc966f036ca"
        starts_at:
          type: string
          format: date-time
          description: When the alert started firing
          example: "2026-04-08T13:28:38Z"
        ends_at:
          type: string
          format: date-time
          nullable: true
          description: When the alert resolved. Null when the end time is unknown.
          example: "2026-04-08T13:33:39Z"
        summary:
          type: string
          nullable: true
          description: Human-readable summary from alert annotations
          example: "Disk usage above 90%"
        labels:
          type: object
          additionalProperties:
            type: string
          description: All labels from the alert
          example:
            alertname: "DiskFull"
            severity: "critical"
            system_key: "NETH-F5D2-5E69-A174-45A9-B1AB-2BB9-03F5-F1B4"
        annotations:
          type: object
          additionalProperties:
            type: string
          description: All annotations from the alert
          example:
            summary: "Disk usage above 90%"
        receiver:
          type: string
          nullable: true
          description: Alertmanager receiver that handled this alert
          example: "severity-critical-receiver"
        created_at:
          type: string
          format: date-time
          description: When the record was created in the database
          example: "2026-04-08T13:33:40Z"

    InventoryRecord:
      type: object
      description: A snapshot of a system's inventory data at a point in time
      properties:
        id:
          type: integer
          format: int64
          description: Auto-incrementing record ID
          example: 42
        system_id:
          type: string
          description: ID of the system that sent the inventory
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        timestamp:
          type: string
          format: date-time
          description: When the inventory was collected on the system
          example: "2026-02-20T14:30:00Z"
        data:
          type: object
          description: >
            Complete raw inventory JSON. Contains the full system inventory payload
            (facts, modules, nodes, network, etc.). The structure varies by system type
            and can contain hundreds of fields.
          example:
            facts:
              distro:
                name: "NethServer"
                version: "8.2.0"
              network:
                hostname: "ns8.example.com"
                public_ip: "203.0.113.10"
              memory:
                total_bytes: 17179869184
        data_hash:
          type: string
          description: SHA-256 hash of the inventory data for deduplication
          example: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        data_size:
          type: integer
          format: int64
          description: Size of the inventory data in bytes
          example: 24576
        processed_at:
          type: string
          format: date-time
          nullable: true
          description: When diff processing completed for this record. Null if not yet processed.
          example: "2026-02-20T14:31:00Z"
        has_changes:
          type: boolean
          description: Whether changes were detected compared to the previous inventory
          example: true
        change_count:
          type: integer
          description: Number of significant changes detected
          example: 5
        created_at:
          type: string
          format: date-time
          description: When the record was created in the database
          example: "2026-02-20T14:30:05Z"
        updated_at:
          type: string
          format: date-time
          description: When the record was last updated
          example: "2026-02-20T14:31:00Z"

    InventoryDiff:
      type: object
      description: A single field-level difference between two inventory snapshots
      properties:
        id:
          type: integer
          format: int64
          description: Auto-incrementing diff ID
          example: 101
        system_id:
          type: string
          description: ID of the system
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        previous_inventory_id:
          type: integer
          format: int64
          nullable: true
          description: ID of the previous inventory record this diff was computed against. Null for the first inventory.
          example: 41
        inventory_id:
          type: integer
          format: int64
          description: ID of the inventory record this diff belongs to
          example: 42
        diff_type:
          type: string
          enum: [create, update, delete]
          description: Type of change detected
          example: "update"
        field_path:
          type: string
          description: JSON path of the changed field (e.g. facts.nodes.1.version)
          example: "facts.distro.version"
        previous_value:
          type: string
          description: Previous field value. Can be a string, number, object, or array depending on the field. Null for 'create' diffs.
          nullable: true
          example: "8.1.0"
        current_value:
          type: string
          description: Current field value. Can be a string, number, object, or array depending on the field. Null for 'delete' diffs.
          nullable: true
          example: "8.2.0"
        severity:
          type: string
          enum: [low, medium, high, critical]
          description: >
            Severity of the change. Determined by the differ engine configuration:
            critical (deleted nodes/memory/network, error entries),
            high (version changes, subscription, certificates),
            medium (feature updates, cluster changes),
            low (uptime, memory usage fluctuations).
          example: "high"
        category:
          type: string
          description: >
            Category of the change. Possible values: os, hardware, network, security,
            backup, features, modules, cluster, nodes, system.
          enum: [os, hardware, network, security, backup, features, modules, cluster, nodes, system]
          example: "os"
        notification_sent:
          type: boolean
          description: Whether a notification has been sent for this change
          example: false
        created_at:
          type: string
          format: date-time
          description: When the diff was created
          example: "2026-02-20T14:31:00Z"

    InventoryChangesSummary:
      type: object
      description: Aggregated summary of inventory changes for a system
      properties:
        system_id:
          type: string
          description: ID of the system
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        total_changes:
          type: integer
          description: Total number of changes across all inventory snapshots
          example: 42
        recent_changes:
          type: integer
          description: Number of changes in the most recent period
          example: 5
        last_inventory_time:
          type: string
          format: date-time
          description: Timestamp of the most recent inventory record
          example: "2026-02-20T14:30:00Z"
        has_critical_changes:
          type: boolean
          description: Whether any critical-severity changes exist
          example: false
        has_alerts:
          type: boolean
          description: Whether any unresolved alerts exist for this system
          example: true
        changes_by_category:
          type: object
          description: Count of changes grouped by category
          additionalProperties:
            type: integer
          example:
            os: 10
            hardware: 5
            network: 8
            security: 3
        changes_by_severity:
          type: object
          description: Count of changes grouped by severity
          additionalProperties:
            type: integer
          example:
            low: 20
            medium: 15
            high: 5
            critical: 2

    InventoryTimelineSummary:
      type: object
      description: Filtered severity counts for the timeline view
      properties:
        total:
          type: integer
          description: Total number of changes matching the active filters
          example: 12
        critical:
          type: integer
          description: Number of critical-severity changes matching the active filters
          example: 1
        high:
          type: integer
          description: Number of high-severity changes matching the active filters
          example: 3
        medium:
          type: integer
          description: Number of medium-severity changes matching the active filters
          example: 8
        low:
          type: integer
          description: Number of low-severity changes matching the active filters
          example: 0

    InventoryTimelineGroup:
      type: object
      description: A date group in the inventory timeline
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format (UTC)
          example: "2026-03-04"
        inventory_count:
          type: integer
          description: Number of inventory snapshots collected on this date
          example: 3
        change_count:
          type: integer
          description: Number of diffs on this date matching the active filters (0 means no changes)
          example: 2
        inventory_ids:
          type: array
          description: IDs of the inventory records collected on this date. Pass these as repeated params to `GET /systems/{id}/inventory/diffs?inventory_id=42&inventory_id=43` to fetch the actual diffs.
          items:
            type: integer
            format: int64
          example: [42, 43]

    BackupMetadata:
      type: object
      description: Metadata describing a single configuration backup stored for a system.
      properties:
        id:
          type: string
          description: Backup object ID (UUIDv7 plus original extension)
          example: "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz"
        filename:
          type: string
          description: User-facing filename as supplied by the appliance via X-Filename
          example: "daily-backup-2026-04-12.tar.gz"
        size:
          type: integer
          format: int64
          description: Object size in bytes
          example: 82944000
        sha256:
          type: string
          description: Hex SHA-256 checksum computed at ingest; always present once the upload returns 201
          example: "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
        mimetype:
          type: string
          example: "application/gzip"
        uploaded_at:
          type: string
          format: date-time
          description: Server-observed timestamp of the upload
          example: "2026-04-12T02:15:00Z"

    Pagination:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: Current page number
          example: 1
        page_size:
          type: integer
          minimum: 1
          maximum: 200
          description: Number of items per page
          example: 20
        total_count:
          type: integer
          minimum: 0
          description: Total number of items
          example: 156
        total_pages:
          type: integer
          minimum: 0
          description: Total number of pages
          example: 8
        has_next:
          type: boolean
          description: Whether there is a next page
          example: true
        has_prev:
          type: boolean
          description: Whether there is a previous page
          example: false
        next_page:
          type: integer
          nullable: true
          description: Next page number if available
          example: 2
        prev_page:
          type: integer
          nullable: true
          description: Previous page number if available
          example: null
        sort_by:
          type: string
          nullable: true
          description: Field used for sorting
          example: "name"
        sort_direction:
          type: string
          nullable: true
          enum: ["asc", "desc"]
          description: Sort direction
          example: "asc"

    TokenExchangeRequest:
      type: object
      required:
        - access_token
      properties:
        access_token:
          type: string
          description: Logto access token to exchange
          example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

    TokenRefreshRequest:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
          description: Refresh token to exchange for new access token
          example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

    ChangePasswordRequest:
      type: object
      required:
        - current_password
        - new_password
      properties:
        current_password:
          type: string
          description: Current user password for verification
          example: "MyCurrentP4ssw0rd!"
        new_password:
          type: string
          minLength: 12
          maxLength: 128
          description: |
            New password meeting security requirements:
            - At least 12 characters long
            - At least one uppercase letter (A-Z)
            - At least one lowercase letter (a-z)
            - At least one digit (0-9)
            - At least one special character (!@#$%^&*...)
            - No more than 3 consecutive identical characters
            - Cannot contain common weak patterns
          example: "MyNewSecureP4ssw0rd!"

    ChangeInfoRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: User's full name (cannot be empty if provided)
          example: "John Doe"
        email:
          type: string
          format: email
          minLength: 1
          description: User's email address (cannot be empty if provided)
          example: "john.doe@example.com"
        phone:
          type: string
          nullable: true
          description: User's phone number (can be empty to remove)
          example: "+39 333 123456"

    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token (24h)
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        refresh_token:
          type: string
          description: Refresh token (7 days)
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        expires_in:
          type: integer
          description: Token expiration time in seconds
          example: 86400
        user:
          $ref: '#/components/schemas/UserProfile'

    UserProfile:
      type: object
      properties:
        id:
          type: string
          description: User ID
          example: "user_123456789"
        logto_id:
          type: string
          nullable: true
          description: Logto user ID
          example: "user_abc123def456"
        username:
          type: string
          description: Username
          example: "john.doe"
        email:
          type: string
          format: email
          description: User email address
          example: "john@example.com"
        name:
          type: string
          description: Full name
          example: "John Doe"
        phone:
          type: string
          nullable: true
          description: Phone number
          example: "+39 333 123456"
        user_roles:
          type: array
          items:
            type: string
          description: User role names
          example: ["Admin"]
        user_role_ids:
          type: array
          items:
            type: string
          description: User role IDs
          example: ["rol_admin_id_123"]
        user_permissions:
          type: array
          items:
            type: string
          description: User permissions from roles
          example: ["destroy:systems", "manage:systems", "read:systems"]
        org_role:
          type: string
          description: Organization role name
          example: "Owner"
        org_role_id:
          type: string
          description: Organization role ID
          example: "org_rol_owner_456"
        org_permissions:
          type: array
          items:
            type: string
          description: Organization permissions
          example: ["create:distributors", "manage:distributors"]
        organization_id:
          type: string
          description: Organization ID
          example: "org_123"
        organization_name:
          type: string
          description: Organization name
          example: "ACME Distribution"

    Organization:
      type: object
      properties:
        id:
          type: string
          description: Database UUID of the organization
          example: "4405ffd0-0aca-44ef-bae2-c8545bce94f4"
        logto_id:
          type: string
          description: Logto organization ID (use this value for assignment operations)
          example: "akkbs6x2wo82"
        name:
          type: string
          description: Organization name
          example: "ACME Distribution SpA"
        description:
          type: string
          description: Organization description
          example: "Main distributor for Italian and Swiss markets"
        custom_data:
          type: object
          description: Custom organization data
          additionalProperties: true
          example:
            email: "contact@acme-distribution.com"
            contactPerson: "John Smith"
            region: "Italy"
        suspended_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the organization was suspended. NULL means enabled, non-NULL means blocked/suspended.
          example: null
        suspended_by_org_id:
          type: string
          nullable: true
          description: Organization ID that caused cascade suspension (for resellers and customers only). NULL means directly suspended or not suspended. When set, the entity can only be reactivated by the parent organization that initiated the cascade.
          example: null
        rebranding_enabled:
          type: boolean
          description: Whether rebranding is active for this organization (directly or inherited from parent)
          example: false
        rebranding_org_id:
          type: string
          nullable: true
          description: The organization ID that provides the rebranding (the org where rebranding is configured). Only present when rebranding_enabled is true.
          example: null

    OrganizationWithStats:
      description: Organization with inline count statistics, returned in list responses
      allOf:
        - $ref: '#/components/schemas/Organization'
        - type: object
          properties:
            systems_count:
              type: integer
              description: Number of systems in this organization
              example: 32
            resellers_count:
              type: integer
              description: Number of resellers created by this distributor (distributors only)
              example: 25
            customers_count:
              type: integer
              description: Number of customers in the hierarchy (distributors and resellers only)
              example: 420
            applications_count:
              type: integer
              description: Number of certified applications (certification_level 4 or 5) in the hierarchy
              example: 15

    OrganizationInput:
      type: object
      required:
        - name
        - custom_data
      properties:
        name:
          type: string
          minLength: 1
          description: Organization name (cannot be empty)
          example: "ACME Distribution SpA"
        description:
          type: string
          description: Organization description
          example: "Main distributor for Italian and Swiss markets"
        custom_data:
          type: object
          description: Custom organization data (vat field is required)
          required:
            - vat
          properties:
            vat:
              type: string
              minLength: 1
              description: VAT number (required, cannot be empty)
              example: "IT12345678901"
          additionalProperties: true
          example:
            vat: "IT12345678901"
            email: "contact@acme-distribution.com"
            contactPerson: "John Smith"
            region: "Italy"

    User:
      type: object
      properties:
        id:
          type: string
          description: User account ID
          example: "usr_123456789"
        logto_id:
          type: string
          nullable: true
          description: Logto user ID
          example: "user_abc123def456"
        username:
          type: string
          description: Username
          example: "john.doe"
        email:
          type: string
          format: email
          description: Email address
          example: "john@example.com"
        name:
          type: string
          description: Full name
          example: "John Doe"
        phone:
          type: string
          nullable: true
          description: Phone number
          example: "+39 333 123456"
        organization:
          description: Organization information (null when not assigned to an organization)
          allOf:
            - $ref: '#/components/schemas/UserOrganization'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: User roles with names
          example: [{"id": "rol_admin_123", "name": "Admin"}]
        custom_data:
          type: object
          description: Custom user data
          additionalProperties: true
          example:
            department: "IT"
            position: "Senior Developer"
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
          example: "2025-06-20T14:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2025-06-21T10:45:00Z"
        logto_synced_at:
          type: string
          format: date-time
          nullable: true
          description: Last Logto synchronization timestamp
          example: "2025-06-21T10:45:00Z"
        latest_login_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last successful login via /auth/exchange endpoint. NULL means user has never logged in.
          example: "2025-06-21T15:30:45Z"
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp (null if not deleted)
          example: null
        suspended_at:
          type: string
          format: date-time
          nullable: true
          description: Suspension timestamp (null if not suspended)
          example: null
        can_be_impersonated:
          type: boolean
          description: Whether this user can currently be impersonated (only shown for users with impersonation permissions, based on active consent)
          example: true

    UserInput:
      type: object
      description: |
        User creation request. Password is automatically generated by the server and sent via email.
      required:
        - email
        - name
        - user_role_ids
        - organization_id
      properties:
        email:
          type: string
          format: email
          description: Email address (username will be generated automatically)
          example: "john.doe@acme.com"
        name:
          type: string
          description: Full name
          example: "John Doe"
        user_role_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: User role IDs to assign
          example: ["rol_abc123def456", "rol_xyz789abc123"]
        organization_id:
          type: string
          description: Organization Logto ID to assign user to (use the logto_id from organization responses)
          example: "akkbs6x2wo82"
        phone:
          type: string
          description: Phone number
          example: "+39 333 123456"
        custom_data:
          type: object
          description: Custom user data
          additionalProperties: true
          example:
            department: "IT"
            position: "Senior Developer"

    UserUpdate:
      type: object
      properties:
        name:
          type: string
          description: Full name
          example: "John Doe (Updated)"
        user_role_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: User role IDs to assign
          example: ["rol_new_role_id_here", "rol_another_id"]
        phone:
          type: string
          description: Phone number
          example: "+39 333 123456"
        custom_data:
          type: object
          description: Custom user data
          additionalProperties: true
          example:
            department: "Sales"
            location: "Rome"

    PasswordResetRequest:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          minLength: 12
          maxLength: 128
          description: |
            Password meeting security requirements:
            - At least 12 characters long
            - At least one uppercase letter (A-Z)
            - At least one lowercase letter (a-z)
            - At least one digit (0-9)
            - At least one special character (!@#$%^&*...)
            - No more than 3 consecutive identical characters
            - Cannot contain common weak patterns
          example: "MySecureP4ssw9rd!"


    Role:
      type: object
      properties:
        id:
          type: string
          description: Role ID
          example: "rol_admin_123"
        name:
          type: string
          description: Role name
          example: "Admin"
        description:
          type: string
          description: Role description
          example: "Full system administration capabilities"

    UserRole:
      type: object
      properties:
        id:
          type: string
          description: Role ID
          example: "rol_admin_123"
        name:
          type: string
          description: Role name
          example: "Admin"

    UserOrganization:
      type: object
      properties:
        id:
          type: string
          description: Local database organization ID
          example: "12345678-1234-1234-1234-123456789abc"
        logto_id:
          type: string
          description: Logto organization ID
          example: "org_123456789"
        name:
          type: string
          description: Organization name
          example: "ACME Corp"
        type:
          type: string
          description: Organization type in the business hierarchy
          enum: ["owner", "distributor", "reseller", "customer"]
          example: "customer"

    OrganizationRole:
      type: object
      properties:
        id:
          type: string
          description: Organization role ID
          example: "org_rol_owner_123"
        name:
          type: string
          description: Organization role name
          example: "Owner"
        description:
          type: string
          description: Organization role description
          example: "Complete control over organization and business hierarchy"

    OrganizationReference:
      type: object
      properties:
        id:
          type: string
          description: Database UUID of the organization
          example: "4405ffd0-0aca-44ef-bae2-c8545bce94f4"
        logto_id:
          type: string
          description: Logto organization ID (use this value for assignment operations)
          example: "akkbs6x2wo82"
        name:
          type: string
          description: Organization name
          example: "ACME Corp"
        description:
          type: string
          description: Organization description
          example: "Main customer organization"
        type:
          type: string
          enum: [owner, distributor, reseller, customer]
          description: Organization type
          example: "customer"

    OrganizationSummary:
      type: object
      description: Simplified organization for selection and assignment
      properties:
        id:
          type: string
          description: Database UUID of the organization (or "no_org" for unassigned filter)
          example: "4405ffd0-0aca-44ef-bae2-c8545bce94f4"
        logto_id:
          type: string
          description: Logto organization ID (or "no_org" for unassigned filter)
          example: "akkbs6x2wo82"
        name:
          type: string
          description: Organization name
          example: "ACME Corp"
        description:
          type: string
          description: Organization description
          example: "Main customer organization"
        type:
          type: string
          enum: [owner, distributor, reseller, customer, unassigned]
          description: Organization type ("unassigned" is the special "No organization" filter entry)
          example: "customer"

    SystemOrganization:
      type: object
      description: Organization information embedded in system response
      properties:
        id:
          type: string
          description: Database UUID of the organization (empty string for owner organization)
          example: "4405ffd0-0aca-44ef-bae2-c8545bce94f4"
        logto_id:
          type: string
          description: Logto organization ID (used for identity/auth purposes)
          example: "akkbs6x2wo82"
        name:
          type: string
          description: Organization name
          example: "ACME Corp"
        type:
          type: string
          enum: [owner, distributor, reseller, customer]
          description: Organization type
          example: "customer"

    ThirdPartyApplication:
      type: object
      properties:
        id:
          type: string
          description: Application ID
          example: "app_123456789"
        name:
          type: string
          description: Application name (FQDN)
          example: "management.company.com"
        description:
          type: string
          description: Application description
          example: "Management interface for system administrators"
        redirect_uris:
          type: array
          items:
            type: string
          description: OAuth redirect URIs
          example: ["https://management.company.com/callback"]
        post_logout_redirect_uris:
          type: array
          items:
            type: string
          description: Post logout redirect URIs
          example: ["https://management.company.com"]
        login_url:
          type: string
          description: OAuth2 login URL with dynamic scopes and parameters
          example: "https://tree6d.logto.app/oidc/auth?client_id=app_123456789&redirect_uri=https%3A%2F%2Fmanagement.company.com%2Fcallback&response_type=code&scope=openid+profile+email+roles&state=random-state-string"
        branding:
          $ref: '#/components/schemas/ApplicationBranding'

    ApplicationBranding:
      type: object
      properties:
        display_name:
          type: string
          description: Application display name
          example: "Management Console"
        logo_url:
          type: string
          description: Application logo URL
          example: "https://cdn.example.com/logos/management-console.png"
        dark_logo_url:
          type: string
          description: Application dark theme logo URL
          example: "https://cdn.example.com/logos/management-console-dark.png"


    SystemTotals:
      type: object
      properties:
        total:
          type: integer
          description: Total number of systems
          example: 1250
        active:
          type: integer
          description: Number of systems that communicated within the last timeout minutes
          example: 1100
        inactive:
          type: integer
          description: Number of systems that communicated but not within timeout minutes
          example: 100
        unknown:
          type: integer
          description: Number of systems that were created but never communicated
          example: 50
        timeout_minutes:
          type: integer
          description: Timeout used for active/inactive determination
          example: 15

    Totals:
      type: object
      properties:
        total:
          type: integer
          description: Total count
          example: 125

    DistributorStats:
      type: object
      description: Statistics for a distributor (users, systems, resellers, customers and applications count)
      properties:
        users_count:
          type: integer
          description: Number of users directly in the distributor organization
          example: 980
        users_hierarchy_count:
          type: integer
          description: Total number of users in the distributor hierarchy (distributor + resellers + customers)
          example: 1500
        systems_count:
          type: integer
          description: Number of systems directly in the distributor organization
          example: 32
        systems_hierarchy_count:
          type: integer
          description: Total number of systems in the distributor hierarchy (distributor + resellers + customers)
          example: 1200
        resellers_count:
          type: integer
          description: Number of resellers created by this distributor
          example: 25
        customers_count:
          type: integer
          description: Number of customers in the distributor hierarchy (via resellers)
          example: 420
        applications_count:
          type: integer
          description: Number of applications directly associated with this distributor
          example: 50
        applications_hierarchy_count:
          type: integer
          description: Total number of applications in the distributor hierarchy (distributor + resellers + customers)
          example: 3246

    ResellerStats:
      type: object
      description: Statistics for a reseller (users, systems, customers and applications count)
      properties:
        users_count:
          type: integer
          description: Number of users directly in the reseller organization
          example: 8
        users_hierarchy_count:
          type: integer
          description: Total number of users in the reseller hierarchy (reseller + customers)
          example: 45
        systems_count:
          type: integer
          description: Number of systems directly in the reseller organization
          example: 32
        systems_hierarchy_count:
          type: integer
          description: Total number of systems in the reseller hierarchy (reseller + customers)
          example: 180
        customers_count:
          type: integer
          description: Number of customers created by this reseller
          example: 252
        applications_count:
          type: integer
          description: Number of applications directly associated with this reseller
          example: 20
        applications_hierarchy_count:
          type: integer
          description: Total number of applications in the reseller hierarchy (reseller + customers)
          example: 500

    CustomerStats:
      type: object
      description: Statistics for a customer (users, systems and applications count)
      properties:
        users_count:
          type: integer
          description: Number of users in the customer organization
          example: 2
        systems_count:
          type: integer
          description: Number of systems in the customer organization
          example: 2
        applications_count:
          type: integer
          description: Number of applications directly associated with this customer
          example: 22

    TrendResponse:
      type: object
      properties:
        period:
          type: integer
          description: Trend period in days
          enum: [7, 30, 180, 365]
          example: 7
        period_label:
          type: string
          description: Human-readable period label
          example: "7 days"
        current_total:
          type: integer
          description: Total count at the end of the period
          example: 15
        previous_total:
          type: integer
          description: Total count at the start of the period
          example: 12
        delta:
          type: integer
          description: Absolute change between start and end
          example: 3
        delta_percentage:
          type: number
          format: float
          description: Percentage change between start and end
          example: 25.0
        trend:
          type: string
          enum: [up, down, stable]
          description: Trend direction
          example: "up"
        data_points:
          type: array
          description: Time-series data points with cumulative counts
          items:
            $ref: '#/components/schemas/TrendDataPoint'

    TrendDataPoint:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Date for this data point
          example: "2025-10-28"
        count:
          type: integer
          description: Cumulative count at this date
          example: 15

    System:
      type: object
      properties:
        id:
          type: string
          description: System ID
          example: "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7"
        name:
          type: string
          description: System name
          example: "Production Server 01"
        type:
          type: string
          nullable: true
          enum: [ns8, nsec]
          description: System type (auto-detected by collect service, null until first inventory collection)
          example: "nsec"
        status:
          type: string
          enum: [unknown, active, inactive, suspended, deleted]
          description: "Unified system status. Priority: suspended > deleted > unknown/active/inactive. Computed from heartbeat + suspension state."
          example: "active"
        fqdn:
          type: string
          description: Fully qualified domain name
          example: "prod-web-01.example.com"
        ipv4_address:
          type: string
          description: IPv4 address
          example: "192.168.1.100"
        ipv6_address:
          type: string
          description: IPv6 address
          example: "2001:db8::1"
        version:
          type: string
          description: System version
          example: "2.1.4"
        system_key:
          type: string
          description: Auto-generated unique commercial system key. Hidden (empty string) until system is registered.
          example: "ABC123DEF456"
        organization:
          $ref: '#/components/schemas/SystemOrganization'
        custom_data:
          type: object
          description: Custom system data
          additionalProperties: true
          example:
            datacenter: "EU-West-1"
            environment: "production"
            tier: "web"
        system_secret:
          type: string
          description: Auto-generated system secret token in format my_<public>.<secret> (only returned during creation/regeneration, never stored or displayed again)
          example: "my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"
        notes:
          type: string
          description: Additional notes or description for the system
          example: "Production web server for EU region"
        created_at:
          type: string
          format: date-time
          description: System creation timestamp
          example: "2025-07-01T09:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: System last update timestamp
          example: "2025-07-10T10:30:00Z"
        created_by:
          $ref: '#/components/schemas/SystemCreator'
        last_heartbeat:
          type: string
          format: date-time
          description: Last heartbeat timestamp
          example: "2025-07-21T10:25:00Z"
        last_inventory:
          type: string
          format: date-time
          nullable: true
          description: Last inventory received timestamp. NULL means no inventory received yet.
          example: "2025-07-21T10:20:00Z"
        registered_at:
          type: string
          format: date-time
          nullable: true
          description: Registration timestamp. NULL means not yet registered, non-NULL means system registered at that time. When NULL, system_key is hidden.
          example: "2025-11-06T10:30:00Z"
        suspended_at:
          type: string
          format: date-time
          nullable: true
          description: Suspension timestamp. NULL means active, non-NULL means suspended.
          example: "2025-11-10T14:00:00Z"
        suspended_by_org_id:
          type: string
          nullable: true
          description: Organization ID that caused cascade suspension (for targeted reactivation).
          example: "org_abc123"
        rebranding_enabled:
          type: boolean
          description: Whether rebranding is active for this system (direct or inherited)
          example: true
        rebranding_org_id:
          type: string
          nullable: true
          description: Logto organization ID (logto_id) that provides the rebranding assets (the org itself or an ancestor). Use this value as the :org_id parameter in /api/rebranding/:org_id/* endpoints.
          example: "org_dist001"

    SystemCreator:
      type: object
      properties:
        user_id:
          type: string
          description: User ID who created the system
          example: "53h5zxpwu4vc"
        name:
          type: string
          description: Full name of the user who created the system
          example: "Edoardo Super"
        email:
          type: string
          description: Email of the user who created the system
          example: "edoardo.spadoni@nethesis.it"
        organization_id:
          type: string
          description: Organization ID of the creator
          example: "lbswt1rxdhbz"
        organization_name:
          type: string
          description: Organization name of the creator
          example: "Nethesis Italia"

    CreateSystemInput:
      type: object
      description: System creation request. Users can create systems for organizations they can manage based on hierarchical permissions.
      required:
        - name
        - organization_id
      properties:
        name:
          type: string
          description: System name
          example: "Production Server 01"
        organization_id:
          type: string
          description: Organization Logto ID to associate the system with (use the logto_id from organization responses)
          example: "akkbs6x2wo82"
        custom_data:
          type: object
          description: Custom system data (optional)
          additionalProperties:
            type: string
          example:
            datacenter: "EU-West-1"
            environment: "production"
            tier: "web"
        notes:
          type: string
          description: Additional notes or description for the system (optional)
          example: "Production web server for EU region"

    UpdateSystemInput:
      type: object
      description: System update request. All fields are optional. Users can update systems created by their organization based on hierarchical permissions.
      properties:
        name:
          type: string
          description: System name
          example: "Production Server 01"
        organization_id:
          type: string
          description: Organization Logto ID to associate the system with (use the logto_id from organization responses)
          example: "akkbs6x2wo82"
        custom_data:
          type: object
          description: Custom system data
          additionalProperties:
            type: string
          example:
            datacenter: "EU-West-1"
            environment: "production"
            tier: "web"
        notes:
          type: string
          description: Additional notes or description for the system
          example: "Production web server for EU region"

    # Applications schemas
    Application:
      type: object
      properties:
        id:
          type: string
          description: Unique application identifier (system_id + module_id)
          example: "sys_abc123_mail1"
        system_id:
          type: string
          description: ID of the system hosting this application
          example: "sys_abc123"
        module_id:
          type: string
          description: Module identifier within the system
          example: "mail1"
        instance_of:
          type: string
          description: Application type (e.g., nethvoice, webtop, mail)
          example: "mail"
        name:
          type: string
          nullable: true
          description: Human-readable label from inventory (e.g., "Nextcloud")
          example: "Nextcloud"
        source:
          type: string
          nullable: true
          description: Image source from inventory (e.g., "ghcr.io/nethserver/nextcloud")
          example: "ghcr.io/nethserver/nextcloud"
        display_name:
          type: string
          nullable: true
          description: User-friendly name set in NS8 and inherited from inventory (e.g., "Milan Office PBX")
          example: "Milan Office PBX"
        node_id:
          type: integer
          nullable: true
          description: Node ID within the cluster
          example: 1
        node_label:
          type: string
          nullable: true
          description: Node label from inventory (e.g., Leader Node, Worker Node)
          example: "Leader Node"
        version:
          type: string
          nullable: true
          description: Application version
          example: "1.2.3"
        organization_id:
          type: string
          nullable: true
          description: Assigned organization ID
          example: "org_xyz789"
        organization_type:
          type: string
          nullable: true
          enum: [distributor, reseller, customer]
          description: Type of the assigned organization
          example: "customer"
        status:
          type: string
          enum: [unassigned, assigned]
          description: Assignment status
          example: "assigned"
        inventory_data:
          type: object
          nullable: true
          description: Raw inventory data from system
          additionalProperties: true
        backup_data:
          type: object
          nullable: true
          description: Backup status information
          additionalProperties: true
        services_data:
          type: object
          nullable: true
          description: Services health status
          additionalProperties: true
        url:
          type: string
          nullable: true
          description: Application URL
          example: "https://cluster.example.com/cluster-admin/#/apps/mail1"
        notes:
          type: string
          nullable: true
          description: Additional notes
          example: "Primary mail server for corporate domain"
        is_user_facing:
          type: boolean
          description: Whether this is a user-facing application (vs system component)
          example: true
        created_at:
          type: string
          format: date-time
          description: Record creation timestamp
          example: "2025-07-01T09:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2025-07-10T10:30:00Z"
        first_seen_at:
          type: string
          format: date-time
          description: First time the application was seen in inventory
          example: "2025-06-15T08:00:00Z"
        last_inventory_at:
          type: string
          format: date-time
          nullable: true
          description: Last inventory collection timestamp
          example: "2025-07-21T10:25:00Z"
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp (null if not deleted)
          example: null
        rebranding_enabled:
          type: boolean
          description: Whether rebranding is active for this application (direct or inherited)
          example: true
        rebranding_org_id:
          type: string
          nullable: true
          description: Logto organization ID (logto_id) that provides the rebranding assets (the org itself or an ancestor). Use this value as the :org_id parameter in /api/rebranding/:org_id/* endpoints.
          example: "org_dist001"
        system:
          $ref: '#/components/schemas/ApplicationSystemSummary'
        organization:
          $ref: '#/components/schemas/OrganizationSummary'

    ApplicationListItem:
      type: object
      description: Simplified application representation for list views
      properties:
        id:
          type: string
          description: Unique application identifier
          example: "sys_abc123_mail1"
        module_id:
          type: string
          description: Module identifier
          example: "mail1"
        instance_of:
          type: string
          description: Application type
          example: "mail"
        name:
          type: string
          nullable: true
          description: Human-readable label from inventory (e.g., "Nextcloud")
          example: "Nextcloud"
        source:
          type: string
          nullable: true
          description: Image source from inventory (e.g., "ghcr.io/nethserver/nextcloud")
          example: "ghcr.io/nethserver/nextcloud"
        display_name:
          type: string
          nullable: true
          description: User-friendly name set in NS8 and inherited from inventory
          example: "Milan Office PBX"
        version:
          type: string
          nullable: true
          description: Application version
          example: "1.2.3"
        status:
          type: string
          enum: [unassigned, assigned]
          description: Assignment status
          example: "assigned"
        node_id:
          type: integer
          nullable: true
          description: Node ID within the cluster
          example: 1
        node_label:
          type: string
          nullable: true
          description: Node label from inventory (e.g., Leader Node, Worker Node)
          example: "Worker Node"
        url:
          type: string
          nullable: true
          description: Custom URL for the application
          example: "https://cluster.example.com/cluster-admin/#/apps/mail1"
        notes:
          type: string
          nullable: true
          description: Custom notes or description for the application
          example: "Corporate email server for marketing department"
        has_errors:
          type: boolean
          description: Whether the application has service errors
          example: false
        inventory_data:
          type: object
          nullable: true
          description: Raw inventory data from the module (e.g., NethVoice proxy, Open LDAP domain, etc.)
          example: {"nethvoice_proxy": "nethvoice-proxy1", "internal_openldap": "mydomain.com"}
        backup_data:
          type: object
          nullable: true
          description: Backup status information
          example: {"status": "success", "destination": "BlackBlaze B1", "completed_at": "2025-09-16T12:30:00Z", "duration_seconds": 106, "total_size_bytes": 9185231897, "total_files": 5759}
        services_data:
          type: object
          nullable: true
          description: Service health status information with errors list
          example: {"has_errors": true, "error_count": 1, "services": [{"name": "NethVoice CTI server", "status": "error", "error": "is not running", "since": "2025-09-16T23:10:00Z"}]}
        system:
          $ref: '#/components/schemas/ApplicationSystemSummary'
        organization:
          $ref: '#/components/schemas/OrganizationSummary'
        created_at:
          type: string
          format: date-time
          description: Record creation timestamp
          example: "2025-07-01T09:00:00Z"
        last_inventory_at:
          type: string
          format: date-time
          nullable: true
          description: Last inventory collection timestamp
          example: "2025-07-21T10:25:00Z"

    ApplicationSystemSummary:
      type: object
      description: Minimal system info for application responses
      properties:
        id:
          type: string
          description: System ID
          example: "sys_abc123"
        name:
          type: string
          description: System name
          example: "Production Cluster"

    ApplicationTotals:
      type: object
      description: Application statistics
      properties:
        total:
          type: integer
          description: Total number of applications
          example: 150
        unassigned:
          type: integer
          description: Number of unassigned applications
          example: 25
        assigned:
          type: integer
          description: Number of assigned applications
          example: 125
        with_errors:
          type: integer
          description: Number of applications with service errors
          example: 5
        by_type:
          type: object
          description: Count by application type
          additionalProperties:
            type: integer
          example:
            mail: 30
            webtop: 25
            nethvoice: 20
            nextcloud: 15
        by_status:
          type: object
          description: Count by status
          additionalProperties:
            type: integer
          example:
            assigned: 125
            unassigned: 25

    ApplicationType:
      type: object
      description: Application type metadata (only user-facing types are returned)
      properties:
        instance_of:
          type: string
          description: Application type identifier (lowercase, e.g., nethvoice, webtop, mail)
          example: "nethvoice"
        name:
          type: string
          description: Human-readable name of the application type (e.g., NethVoice, WebTop)
          example: "NethVoice"
        count:
          type: integer
          description: Number of applications of this type
          example: 30

    ApplicationTypeSummary:
      type: object
      description: Applications grouped by type with total count and optional pagination
      properties:
        total:
          type: integer
          description: Total number of matching applications (always present, not paginated)
          example: 130
        by_type:
          type: array
          description: Applications grouped by type, sorted and optionally paginated
          items:
            $ref: '#/components/schemas/ApplicationType'
        pagination:
          description: Pagination metadata (only present when page_size query param is specified)
          $ref: '#/components/schemas/Pagination'

    AssignApplicationRequest:
      type: object
      required:
        - organization_id
      properties:
        organization_id:
          type: string
          description: Organization Logto ID to assign to the application (use the logto_id from organization responses)
          example: "akkbs6x2wo82"

    UpdateApplicationRequest:
      type: object
      description: Request to update application notes (other fields are read-only and populated from inventory)
      properties:
        notes:
          type: string
          nullable: true
          description: Custom notes for the application
          example: "Server di posta aziendale per il reparto marketing"

    ImpersonationConsent:
      type: object
      properties:
        id:
          type: string
          description: Consent ID
          example: "consent_123"
        user_id:
          type: string
          description: User ID who grants consent
          example: "usr_456"
        expires_at:
          type: string
          format: date-time
          description: Consent expiration timestamp
          example: "2025-09-04T14:30:00Z"
        max_duration_minutes:
          type: integer
          description: Maximum duration for each impersonation session in minutes
          example: 60
        created_at:
          type: string
          format: date-time
          description: Consent creation timestamp
          example: "2025-09-03T14:30:00Z"

    ImpersonationSession:
      type: object
      properties:
        session_id:
          type: string
          description: Unique session identifier
          example: "sess_abc123def456"
        impersonator_user_id:
          type: string
          description: User ID of the person doing the impersonation
          example: "usr_owner_123"
        impersonated_user_id:
          type: string
          description: User ID of the person being impersonated
          example: "usr_target_456"
        impersonator_username:
          type: string
          description: Username of the impersonator
          example: "owner@company.com"
        impersonated_username:
          type: string
          description: Username of the impersonated user
          example: "customer@example.com"
        impersonator_name:
          type: string
          description: Full name of the impersonator
          example: "John Doe"
        impersonated_name:
          type: string
          description: Full name of the impersonated user
          example: "Jane Smith"
        start_time:
          type: string
          format: date-time
          description: Session start timestamp
          example: "2025-09-02T14:30:00Z"
        end_time:
          type: string
          format: date-time
          nullable: true
          description: Session end timestamp (null if still active)
          example: "2025-09-02T15:45:00Z"
        duration_minutes:
          type: integer
          nullable: true
          description: Session duration in minutes (null if still active)
          example: 75
        action_count:
          type: integer
          description: Number of actions performed in this session
          example: 24
        status:
          type: string
          enum: [active, completed]
          description: Session status
          example: "completed"

    ImpersonationAuditEntry:
      type: object
      properties:
        id:
          type: string
          description: Audit entry ID
          example: "audit_xyz789abc"
        session_id:
          type: string
          description: Impersonation session ID
          example: "sess_abc123def456"
        impersonator_user_id:
          type: string
          description: User ID of the person doing the impersonation
          example: "usr_owner_123"
        impersonated_user_id:
          type: string
          description: User ID of the person being impersonated
          example: "usr_target_456"
        impersonator_username:
          type: string
          description: Username of the impersonator
          example: "owner@company.com"
        impersonated_username:
          type: string
          description: Username of the impersonated user
          example: "customer@example.com"
        impersonator_name:
          type: string
          description: Full name of the impersonator
          example: "John Doe"
        impersonated_name:
          type: string
          description: Full name of the impersonated user
          example: "Jane Smith"
        action_type:
          type: string
          enum: [session_start, session_end, api_call]
          description: Type of action performed
          example: "api_call"
        api_endpoint:
          type: string
          nullable: true
          description: API endpoint called (only for api_call actions)
          example: "/api/users"
        http_method:
          type: string
          nullable: true
          description: HTTP method used (only for api_call actions)
          example: "GET"
        request_data:
          type: string
          nullable: true
          description: Request data (only for api_call actions)
          example: "{\"limit\": 10}"
        response_status:
          type: integer
          nullable: true
          description: HTTP response status (only for api_call actions)
          example: 200
        timestamp:
          type: string
          format: date-time
          description: When this action occurred
          example: "2025-09-02T14:32:15Z"

    # ===========================================
    # REBRANDING SCHEMAS
    # ===========================================

    RebrandableProduct:
      type: object
      properties:
        id:
          type: string
          example: "nethvoice"
        display_name:
          type: string
          example: "NethVoice"
        type:
          type: string
          enum: [application, system]
          example: "application"
        created_at:
          type: string
          format: date-time

    RebrandingProductStatus:
      type: object
      properties:
        product_id:
          type: string
          example: "nethvoice"
        product_display_name:
          type: string
          example: "NethVoice"
        product_type:
          type: string
          enum: [application, system]
        product_name:
          type: string
          nullable: true
          example: "CustomVoice"
        assets:
          type: array
          items:
            type: string
          example: ["logo_light_rect", "logo_dark_rect", "favicon"]

    RebrandingOrgStatus:
      type: object
      properties:
        enabled:
          type: boolean
        products:
          type: array
          items:
            $ref: '#/components/schemas/RebrandingProductStatus'

    SystemRebrandingProduct:
      type: object
      properties:
        product_id:
          type: string
          example: "nethvoice"
        product_name:
          type: string
          nullable: true
          example: "CustomVoice"
        assets:
          type: object
          additionalProperties:
            type: string
          example:
            logo_light_rect: "/api/systems/rebranding/nethvoice/logo_light_rect"
            favicon: "/api/systems/rebranding/nethvoice/favicon"

    SystemRebrandingResponse:
      type: object
      properties:
        enabled:
          type: boolean
        inherited_from:
          type: string
          nullable: true
          example: "distributor:org_abc123"
        system:
          type: array
          items:
            $ref: '#/components/schemas/SystemRebrandingProduct'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/SystemRebrandingProduct'

    # ==========================================================================
    # CSV IMPORT SCHEMAS
    # ==========================================================================

    ImportFieldError:
      type: object
      description: |
        Field-level diagnostic returned by `/import/validate`. The same struct is used inside
        both `errors[]` (blocking — row will never be imported) and `warnings[]` (non-blocking —
        row can be turned into an UPDATE by passing `override: true` to `/import/confirm`).

        Conventions:
          - `field` is the CSV column the diagnostic refers to.
          - `message` is a stable machine-readable code, kept short and field-agnostic — the
            field is already in `field`, the frontend builds the localised string by keying off
            `(field, message)` (or just `message` for a generic fallback).
          - `values` is an ordered list of message-specific parameters: the frontend
            substitutes `values[i]` positionally into the i18n template. The slot order per
            code is documented in the tables below. Codes whose row says `—` carry no values.
          - `candidates` is populated only when `message=ambiguous`.

        **Error codes (always blocking)**

        | Code | Where it can occur | `values` slots | Meaning |
        |------|--------------------|---------------|---------|
        | `required` | any required field | — | Field is empty or whitespace |
        | `too_long` | any string field | `[value]` | Value exceeds the field max length |
        | `invalid_format` | `email`, `phone`, `language` | `[value]` | Value is not a valid email / phone / language code. For `phone` this also catches a missing leading `+CC` |
        | `invalid_value` | enum-like fields | `[value]` | Value is not in the allowed set |
        | `duplicate_in_csv` | `email` (users), `vat_number` (orgs) | `[value, firstRowNumber]` | Same value appears in an earlier row of the same file (slot 1 is the row number as a string, e.g. `"2"`). Org `company_name` is NOT checked for duplicates because the DB does not enforce name uniqueness on any org type |
        | `not_found` | `company_name` (users) | `[value]` | Value does not match any entity in the caller's hierarchy |
        | `lookup_failed` | `company_name` (users) | `[value]` | Database error while resolving the value (transient — retry) |
        | `ambiguous` | `company_name` (users) | `[value]` | Multiple matches for the value; `candidates` is populated and must be resolved at confirm. Row status is `ambiguous` |
        | `unknown` | `roles` (users) | `[name1, name2, …]` | One or more values are not recognised; each unknown entry occupies its own slot |
        | `at_least_one_required` | `roles` (users) | — | Field present but parsed to zero entries |
        | `insufficient_privileges` | `roles` (users) | `[value]` | Caller cannot assign one of the requested roles |
        | `already_used` | `phone` (users) | `[value, otherEmail]` | Value is already in use by a *different* entity. For `phone`, slot 1 is the email of the user that already owns it. Logto enforces uniqueness, so the row would otherwise fail at confirm time |
        | `archived` | `email` (users), `vat_number` (distributors, resellers) | `[value]` | The value matches a soft-deleted entity. The row cannot be imported as-is — the admin must restore (and re-run import) or destroy definitively first. Customers carry no DB-level uniqueness so this code is never emitted for them |

        **Warning codes (non-blocking, override-able)**

        | Code | Where it can occur | `values` slots | Meaning |
        |------|--------------------|---------------|---------|
        | `already_exists` | `email` (users), `vat_number` (distributors, resellers) | `[value]` | An active entity with the same key already exists. Row status is `warning` — pass `override: true` at confirm to turn this into an UPDATE instead of a CREATE. Customers never emit this code (no DB-level uniqueness on either name or VAT) |
      properties:
        field:
          type: string
          description: Name of the CSV column the diagnostic refers to.
          example: "email"
        message:
          type: string
          description: Stable, field-agnostic i18n key (see tables above).
          example: "invalid_format"
        values:
          type: array
          items:
            type: string
          description: |
            Ordered list of message-specific parameters. Frontend substitutes them positionally
            into the i18n template using the slot order documented per `message` above.
            Omitted when the message takes no parameters (e.g. `required`).
          example: ["not-an-email"]
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/ImportOrgCandidate'
          description: Candidate organizations to choose from. Populated only when `message=ambiguous`.

    ImportOrgCandidate:
      type: object
      properties:
        logto_id:
          type: string
          description: Organization Logto ID — pass this back as `organization_id` in `resolutions` at confirm time
          example: "abc123"
        name:
          type: string
          description: Organization name as stored in the database
          example: "Acme Corp"
        type:
          type: string
          enum: [distributor, reseller, customer]
          description: Organization type
          example: "distributor"

    ImportRow:
      type: object
      properties:
        row_number:
          type: integer
          description: CSV row number (1-indexed, excluding header — i.e. the first data row is `2`)
          example: 2
        status:
          type: string
          enum: [valid, error, warning, ambiguous]
          description: |
            Validation verdict for the row:
            - `valid` — passes all checks; will be CREATEd by `/import/confirm`.
            - `error` — at least one blocking error (see `errors[]`). Always skipped at confirm.
            - `warning` — entity already exists in the DB (see `warnings[]`). At confirm time it is **UPDATEd** with the CSV values when `override: true` is passed, otherwise skipped.
            - `ambiguous` — only for users: the `organization` name matches multiple orgs in the caller's hierarchy. Must be resolved at confirm time via `resolutions[row_number].organization_id`, otherwise skipped.

            Status precedence: `error` > `ambiguous` > `warning` > `valid`. When a row qualifies for multiple categories (e.g. has both an error and a warning), the higher-precedence one wins; the lower-precedence diagnostics are still reported in their array for context.
        data:
          type: object
          description: |
            Parsed CSV row. For users, the backend additionally enriches it with `organization_id` (resolved Logto ID, empty string if unresolved) and `role_ids` (array of resolved role IDs).
          additionalProperties: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ImportFieldError'
          description: |
            Blocking field-level errors. Empty/omitted when none. For `ambiguous` rows contains exactly one entry with `message=ambiguous` and populated `candidates`.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ImportFieldError'
          description: |
            Non-blocking diagnostics. Empty/omitted when none. Currently only `already_exists` is emitted as a warning. Rows that have only warnings (no errors, no ambiguity) get `status=warning` and can be turned into UPDATEs with `override: true`.

    ImportValidationResult:
      type: object
      description: |
        Row-by-row validation report produced by `/import/validate`. The full set of CSV rows is
        always returned in `rows` (good and bad alike) so the frontend can render a preview and
        let the user decide whether to enable `override` for warnings or pick `resolutions` for
        ambiguous rows. The accompanying counters are pre-computed for UX summaries.
      properties:
        import_id:
          type: string
          format: uuid
          description: Session ID — must be passed verbatim to `/import/confirm`. Sessions expire after 30 minutes.
          example: "550e8400-e29b-41d4-a716-446655440000"
        total_rows:
          type: integer
          description: Number of data rows in the CSV (excluding the header row)
          example: 6
        valid_rows:
          type: integer
          example: 2
        error_rows:
          type: integer
          example: 2
        warning_rows:
          type: integer
          description: "Rows where the entity already exists in the DB. They will be UPDATEd if the caller passes `override: true` at confirm time, otherwise skipped."
          example: 1
        ambiguous_rows:
          type: integer
          description: Rows where the organization name matches multiple organizations and requires disambiguation at confirm time
          example: 1
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ImportRow'
      example:
        import_id: "3312b187-a8b0-45f5-b23a-98798b64eb31"
        total_rows: 6
        valid_rows: 2
        error_rows: 2
        warning_rows: 1
        ambiguous_rows: 1
        rows:
          - row_number: 2
            status: valid
            data:
              email: "marco.rossi@nethesis.it"
              name: "Marco Rossi"
              phone: "+39 333 1234567"
              company_name: "Acme Corp"
              organization_id: "zm45rltjc9rr"
              roles: "Admin"
              role_ids: ["7jmz7ryag1m254m4428n8"]
          - row_number: 3
            status: valid
            data:
              email: "support@beta.it"
              name: "Beta Support"
              phone: ""
              company_name: "Beta Solutions"
              organization_id: "jl6lgn3l6nsi"
              roles: "Support"
              role_ids: ["77evvdf876ze8oykdk4y9"]
          - row_number: 4
            status: error
            data:
              email: "not-an-email"
              name: "Bad Email"
              phone: "+39 333 0000000"
              company_name: "Acme Corp"
              organization_id: ""
              roles: "Admin"
              role_ids: ["7jmz7ryag1m254m4428n8"]
            errors:
              - field: "email"
                message: "invalid_format"
                values: ["not-an-email"]
          - row_number: 5
            status: error
            data:
              email: "test@nethesis.it"
              name: "Wrong Org"
              phone: ""
              company_name: "Organization That Does Not Exist"
              organization_id: ""
              roles: "Support"
              role_ids: ["77evvdf876ze8oykdk4y9"]
            errors:
              - field: "company_name"
                message: "not_found"
                values: ["Organization That Does Not Exist"]
          - row_number: 6
            status: warning
            data:
              email: "edoardo.spadoni@nethesis.it"
              name: "Mario Rossi"
              phone: ""
              company_name: "Acme Corp"
              organization_id: "zm45rltjc9rr"
              roles: "Admin"
              role_ids: ["7jmz7ryag1m254m4428n8"]
            warnings:
              - field: "email"
                message: "already_exists"
                values: ["edoardo.spadoni@nethesis.it"]
          - row_number: 7
            status: ambiguous
            data:
              email: "ambig@nethesis.it"
              name: "Ambiguous Org"
              phone: ""
              company_name: "Gamma"
              organization_id: ""
              roles: "Support"
              role_ids: ["77evvdf876ze8oykdk4y9"]
            errors:
              - field: "company_name"
                message: "ambiguous"
                values: ["Gamma"]
                candidates:
                  - logto_id: "abc123"
                    name: "Gamma Tech"
                    type: "distributor"
                  - logto_id: "def456"
                    name: "Gamma Group"
                    type: "customer"

    ImportConfirmRequest:
      type: object
      required:
        - import_id
      description: |
        Body of `/import/confirm`. The backend computes skips automatically based on the
        validate report — there is no `skip_rows` field. The caller only chooses two things:

        - `override` — global toggle. When `true`, every row with status `warning` (entity
          already exists in DB) is UPDATEd with the CSV values instead of being skipped.
          When `false` or omitted, warning rows are skipped.
        - `resolutions` — per-row choice for rows with status `ambiguous` (only happens for
          users when the organization name matches multiple orgs).
      properties:
        import_id:
          type: string
          format: uuid
          description: Import session ID from the validate response. Sessions expire after 30 min.
          example: "550e8400-e29b-41d4-a716-446655440000"
        override:
          type: boolean
          default: false
          description: |
            When `true`, all rows with status `warning` are UPDATEd using the CSV values
            (existing entity is looked up by email/name and overwritten field-by-field).
            When `false` or omitted, warning rows are skipped.
          example: true
        resolutions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ImportResolution'
          description: |
            Per-row organization choices for `ambiguous` rows, keyed by row number as a string
            (e.g. `"7"`). The chosen `organization_id` must be one of the `candidates[].logto_id`
            values returned by `/import/validate` for that row. Ambiguous rows without a
            resolution are skipped.
          example:
            "7":
              organization_id: "abc123"
      example:
        import_id: "3312b187-a8b0-45f5-b23a-98798b64eb31"
        override: true
        resolutions:
          "7":
            organization_id: "abc123"

    ImportResolution:
      type: object
      required:
        - organization_id
      properties:
        organization_id:
          type: string
          description: The chosen organization Logto ID — must match one of the `candidates[].logto_id` returned for that row
          example: "abc123"

    ImportResultRow:
      type: object
      properties:
        row_number:
          type: integer
          example: 2
        status:
          type: string
          enum: [created, updated, skipped, failed]
          description: |
            Per-row outcome:
            - `created` — entity successfully created (`id` populated).
            - `updated` — entity already existed and was overwritten (only when `override: true` was passed and the row had status `warning` at validate time). `id` populated.
            - `skipped` — row was not imported. The `reason` field explains why.
            - `failed` — import was attempted but rejected (e.g. Logto sync failure, RBAC denial when moving a user to a non-managed org). `error` populated.
        id:
          type: string
          description: Entity ID. Populated when status is `created` or `updated`.
          example: "usr_2k3lf9d8sn"
        reason:
          type: string
          enum: [error, warning_not_overridden, ambiguous_unresolved]
          description: |
            Populated only when status is `skipped`:
            - `error` — the row had blocking errors at validate time.
            - `warning_not_overridden` — the row was a `warning` (existing entity) but `override` was not set.
            - `ambiguous_unresolved` — the row was `ambiguous` and no resolution was provided.
        error:
          type: string
          description: Failure reason. Populated only when status is `failed`.
          example: "logto sync failed: rate limit exceeded"

    ImportConfirmResult:
      type: object
      description: |
        Per-row outcome of `/import/confirm`. The operation is non-atomic: a partial failure does
        not roll back the rows that were already created or updated. The four counters always
        sum to `total_rows` of the validate response.
      properties:
        created:
          type: integer
          example: 2
        updated:
          type: integer
          example: 1
        skipped:
          type: integer
          example: 2
        failed:
          type: integer
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/ImportResultRow'
      example:
        created: 2
        updated: 1
        skipped: 2
        failed: 1
        results:
          - row_number: 2
            status: created
            id: "usr_2k3lf9d8sn"
          - row_number: 3
            status: created
            id: "usr_8skd0w29df"
          - row_number: 4
            status: skipped
            reason: "error"
          - row_number: 5
            status: skipped
            reason: "error"
          - row_number: 6
            status: updated
            id: "usr_existing01"
          - row_number: 7
            status: failed
            error: "logto sync failed: rate limit exceeded"

  parameters:
    PageParam:
      name: page
      in: query
      description: Page number
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1

    PageSizeParam:
      name: page_size
      in: query
      description: Items per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
        example: 20

    DistributorSortByParam:
      name: sort_by
      in: query
      description: Field to sort distributors by
      required: false
      schema:
        type: string
        enum: ["name", "description", "created_at", "updated_at", "suspended_at"]
        example: "name"

    ResellerSortByParam:
      name: sort_by
      in: query
      description: Field to sort resellers by
      required: false
      schema:
        type: string
        enum: ["name", "description", "created_at", "updated_at", "suspended_at"]
        example: "name"

    CustomerSortByParam:
      name: sort_by
      in: query
      description: Field to sort customers by
      required: false
      schema:
        type: string
        enum: ["name", "description", "created_at", "updated_at", "suspended_at"]
        example: "name"

    OrganizationStatusFilterParam:
      name: status
      in: query
      description: |
        Filter organizations by status. Supports multiple values.

        - enabled: not suspended and not deleted
        - suspended: suspended but not deleted
        - deleted: soft-deleted

        When "deleted" is combined with other statuses, both deleted and non-deleted matching records are returned.
      required: false
      schema:
        type: array
        items:
          type: string
          enum: ["enabled", "suspended", "deleted"]
        example: ["enabled"]
      style: form
      explode: true

    UserSortByParam:
      name: sort_by
      in: query
      description: Field to sort users by
      required: false
      schema:
        type: string
        enum: ["name", "email", "username", "created_at", "updated_at", "latest_login_at", "organization", "status"]
        example: "name"

    SystemSortByParam:
      name: sort_by
      in: query
      description: Field to sort systems by
      required: false
      schema:
        type: string
        enum: ["name", "type", "status", "fqdn", "version", "system_key", "created_at", "updated_at", "creator_name", "organization_name"]
        example: "name"

    TrendPeriodParam:
      name: period
      in: query
      description: Trend analysis period in days
      required: false
      schema:
        type: integer
        enum: [7, 30, 180, 365]
        default: 7
        example: 7

    SystemNameFilterParam:
      name: name
      in: query
      description: Filter systems by name (case-insensitive, partial match)
      required: false
      schema:
        type: string
        example: "backup-server"

    SystemKeyFilterParam:
      name: system_key
      in: query
      description: Filter systems by system key (exact match). Useful for exporting a single system.
      required: false
      schema:
        type: string
        example: "NETH-DD09-3DB4-76E4-42A0-A6CC-6D30-9AE7-3216"

    SystemTypeFilterParam:
      name: type
      in: query
      description: Filter systems by type/product (exact match). Supports multiple values for checkbox filtering.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["nsec", "ns8"]
      style: form
      explode: true

    SystemCreatedByFilterParam:
      name: created_by
      in: query
      description: |
        Filter systems by creator user ID or creator organization ID (exact match).
        Each provided ID is checked against both the user_id and organization_id fields of the system creator.
        Supports multiple values for checkbox filtering.

        Examples:
        - `?created_by=53h5zxpwu4vc` - matches systems created by user with ID 53h5zxpwu4vc
        - `?created_by=lbswt1rxdhbz` - matches systems created by users in organization lbswt1rxdhbz
        - `?created_by=53h5zxpwu4vc&created_by=lbswt1rxdhbz` - matches systems created by the user OR by users in the organization
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["53h5zxpwu4vc", "lbswt1rxdhbz"]
      style: form
      explode: true

    SystemVersionFilterParam:
      name: version
      in: query
      description: |
        Filter systems by version using prefixed format `product:version` (e.g., `nsec:8.0`, `ns8:1.2.3`).
        The prefix prevents ambiguity when the same version number exists for multiple products.
        Supports multiple values for checkbox filtering.

        **Example**: `?version=nsec:8.0&version=ns8:1.2.3` matches systems with (nsec version 8.0) OR (ns8 version 1.2.3)

        **Backward compatibility**: Non-prefixed versions (e.g., `8.0`) are still supported but may match multiple products.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["nsec:8.0", "nsec:8.1", "ns8:1.2.3"]
      style: form
      explode: true

    SystemOrganizationFilterParam:
      name: organization_id
      in: query
      description: Filter systems by organization ID (exact match). Supports multiple values for checkbox filtering.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["org_abc123xyz", "org_def456uvw"]
      style: form
      explode: true

    SystemStatusFilterParam:
      name: status
      in: query
      description: |
        Filter systems by status. Supports multiple values.

        - unknown, active, inactive, deleted: match the system status column
        - suspended: virtual status matching systems with suspended_at IS NOT NULL

        Special value "deleted" shows soft-deleted systems (where deleted_at IS NOT NULL).
        When "deleted" is combined with other statuses, both deleted and non-deleted systems matching the other statuses are returned.
      required: false
      schema:
        type: array
        items:
          type: string
          enum: ["unknown", "active", "inactive", "suspended", "deleted"]
        example: ["active", "unknown"]
      style: form
      explode: true

    # Applications parameters
    AppSortByParam:
      name: sort_by
      in: query
      description: Field to sort applications by
      required: false
      schema:
        type: string
        enum: ["display_name", "module_id", "instance_of", "version", "status", "created_at", "updated_at", "last_inventory_at", "system_name", "organization_name", "certification_level"]
        example: "instance_of"

    AppTypeFilterParam:
      name: type
      in: query
      description: Filter applications by type (instance_of). Supports multiple values.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["mail", "webtop", "nethvoice"]
      style: form
      explode: true

    AppVersionFilterParam:
      name: version
      in: query
      description: |
        Filter applications by version. Supports multiple values.
        Uses prefixed format "application:version" (e.g., "nethvoice:1.5.3") to avoid ambiguity
        when the same version exists for multiple application types.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["nethvoice:1.5.3", "mail:1.7.4"]
      style: form
      explode: true

    AppSystemFilterParam:
      name: system_id
      in: query
      description: Filter applications by system ID. Supports multiple values.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["sys_abc123", "sys_def456"]
      style: form
      explode: true

    AppOrganizationFilterParam:
      name: organization_id
      in: query
      description: Filter applications by organization ID. Supports multiple values.
      required: false
      schema:
        type: array
        items:
          type: string
        example: ["org_abc123", "org_def456"]
      style: form
      explode: true

    AppStatusFilterParam:
      name: status
      in: query
      description: Filter applications by assignment status. Supports multiple values.
      required: false
      schema:
        type: array
        items:
          type: string
          enum: ["unassigned", "assigned"]
        example: ["unassigned"]
      style: form
      explode: true

    SortDirectionParam:
      name: sort_direction
      in: query
      description: Sort direction
      required: false
      schema:
        type: string
        enum: ["asc", "desc"]
        default: "asc"
        example: "asc"

    SearchParam:
      name: search
      in: query
      description: Search term. For organizations (distributors, resellers, customers), searches across name, description, and all custom_data fields (vat, address, city, contact, email, phone, language, notes, etc.). For systems, also searches across ipv4_address and ipv6_address.
      required: false
      schema:
        type: string
        minLength: 1
        example: "acme"

  responses:
    BadRequest:
      description: Bad request - validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Unauthorized:
      description: Unauthorized - invalid or missing token
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 401
              message:
                type: string
                example: "invalid token"
              data:
                type: object
                nullable: true
                example: null

    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 403
              message:
                type: string
                example: "insufficient permissions"
              data:
                type: object
                nullable: true
                example: null

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    UnprocessableEntity:
      description: Unprocessable entity - business logic error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    RequestEntityTooLarge:
      description: Payload too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 500
              message:
                type: string
                example: "internal server error"
              data:
                type: object
                nullable: true
                example: null

paths:
  # ===========================================================================
  # USER MANAGEMENT
  # ===========================================================================
  /users:
    get:
      operationId: getUsers
      tags:
        - Backend - Users
      summary: /users - List users
      description: Get paginated list of users with hierarchical authorization
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/UserSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - name: organization_id
          in: query
          required: false
          description: Filter by organization logto_id. Supports multiple values.
          schema:
            type: array
            items:
              type: string
            example: ["org_abc123"]
          style: form
          explode: true
        - name: status
          in: query
          required: false
          description: |
            Filter by user status. Supports multiple values.

            - enabled: not suspended and not deleted
            - suspended: suspended but not deleted
            - deleted: soft-deleted
          schema:
            type: array
            items:
              type: string
              enum: [enabled, suspended, deleted]
            example: ["enabled"]
          style: form
          explode: true
        - name: role
          in: query
          required: false
          description: Filter by user role ID. Supports multiple values.
          schema:
            type: array
            items:
              type: string
            example: ["role_abc123"]
          style: form
          explode: true
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "users retrieved successfully"
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      operationId: createUser
      tags:
        - Backend - Users
      summary: /users - Create user
      description: Create a new user with hierarchical authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "user created successfully"
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /users/{id}:
    get:
      operationId: getUserById
      tags:
        - Backend - Users
      summary: /users/{id} - Get single user
      description: Get a specific user by ID with hierarchical authorization
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user retrieved successfully"
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateUser
      tags:
        - Backend - Users
      summary: /users/{id} - Update user
      description: Update a user with hierarchical authorization
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user updated successfully"
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

    delete:
      operationId: deleteUser
      tags:
        - Backend - Users
      summary: /users/{id} - Delete user
      description: Delete a user with hierarchical authorization
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user deleted successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{id}/password:
    patch:
      operationId: resetUserPassword
      tags:
        - Backend - Users
      summary: /users/{id}/password - Reset user password
      description: Reset a user's password (Admin only)
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetRequest'
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "password reset successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{id}/avatar:
    put:
      operationId: uploadUserAvatar
      tags:
        - Backend - Users
      summary: /users/{id}/avatar - Upload user avatar (admin)
      description: |
        Upload a profile image for another user.
        Requires manage:users permission and hierarchical access to the target user.
        Self-modification is prevented (use PUT /me/avatar instead).
        The image is validated, resized to 256x256 pixels if larger, re-encoded as PNG, and stored in the database.
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - avatar
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Avatar image file (PNG, JPEG, or WebP, max 500KB, resized to 256x256)
      responses:
        '200':
          description: Avatar uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "avatar uploaded successfully"
                  data:
                    type: object
                    properties:
                      avatar_url:
                        type: string
                        description: Public URL of the uploaded avatar
                        example: "https://my.nethesis.it/api/public/users/jf584cz36kce/avatar"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteUserAvatar
      tags:
        - Backend - Users
      summary: /users/{id}/avatar - Delete user avatar (admin)
      description: |
        Remove the profile image for another user.
        Requires manage:users permission and hierarchical access to the target user.
        Self-modification is prevented (use DELETE /me/avatar instead).
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Avatar deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "avatar deleted successfully"
                  data:
                    type: object
                    nullable: true
                    example: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /users/{id}/suspend:
    patch:
      operationId: suspendUser
      tags:
        - Backend - Users
      summary: /users/{id}/suspend - Suspend user
      description: Suspend a user (requires manage:users permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user suspended successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{id}/reactivate:
    patch:
      operationId: reactivateUser
      tags:
        - Backend - Users
      summary: /users/{id}/reactivate - Reactivate suspended user
      description: Reactivate a suspended user (requires manage:users permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user reactivated successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{id}/restore:
    patch:
      operationId: restoreUser
      tags:
        - Backend - Users
      summary: /users/{id}/restore - Restore soft-deleted user
      description: Restore a soft-deleted user (requires manage:users permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user restored successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          description: Bad request - User is not deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "user is not deleted"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/{id}/destroy:
    delete:
      operationId: destroyUser
      tags:
        - Backend - Users
      summary: /users/{id}/destroy - Permanently delete user
      description: Permanently delete a user (requires destroy:users permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: User permanently destroyed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user permanently destroyed"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /users/totals:
    get:
      operationId: getUsersTotals
      tags:
        - Backend - Users Stats
      summary: /users/totals - Get users totals
      description: Get total count of users accessible to the user (Admin role required)
      responses:
        '200':
          description: Users totals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "users totals retrieved"
                  data:
                    $ref: '#/components/schemas/Totals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /users/trend:
    get:
      operationId: getUsersTrend
      tags:
        - Backend - Users Stats
      summary: /users/trend - Get users trend data
      description: Get trend analysis of users over time with cumulative counts (respects hierarchical organization filtering)
      parameters:
        - $ref: '#/components/parameters/TrendPeriodParam'
      responses:
        '200':
          description: Users trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "users trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /users/export:
    get:
      operationId: exportUsers
      tags:
        - Backend - Users Import/Export
      summary: /users/export - Export users to CSV or PDF
      description: Export users to CSV or PDF format with applied filters (max 10,000 users)
      parameters:
        - name: format
          in: query
          required: true
          description: Export format (csv or pdf)
          schema:
            type: string
            enum: [csv, pdf]
            example: "csv"
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/UserSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - name: organization_id
          in: query
          required: false
          description: Filter by organization logto_id. Supports multiple values.
          schema:
            type: array
            items:
              type: string
            example: ["org_abc123"]
          style: form
          explode: true
        - name: status
          in: query
          required: false
          description: |
            Filter by user status. Supports multiple values.

            - enabled: not suspended and not deleted
            - suspended: suspended but not deleted
            - deleted: soft-deleted
          schema:
            type: array
            items:
              type: string
              enum: [enabled, suspended, deleted]
            example: ["enabled"]
          style: form
          explode: true
        - name: role
          in: query
          required: false
          description: Filter by user role ID. Supports multiple values.
          schema:
            type: array
            items:
              type: string
            example: ["role_abc123"]
          style: form
          explode: true
      responses:
        '200':
          description: Users exported successfully
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # USERS IMPORT
  # ===========================================================================
  /users/import/template:
    get:
      operationId: getUsersImportTemplate
      tags:
        - Backend - Users Import/Export
      summary: /users/import/template - Download CSV import template
      description: |
        Download a UTF-8 CSV file pre-populated with the expected header row and a few example
        data rows for the user import flow. Columns: `email`, `name`, `phone`, `company_name`,
        `roles`. Sent as a `text/csv` attachment with `Content-Disposition: attachment; filename="users_import_template.csv"`.
      responses:
        '200':
          description: CSV template downloaded
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /users/import/validate:
    post:
      operationId: validateUsersImport
      tags:
        - Backend - Users Import/Export
      summary: /users/import/validate - Validate CSV file for user import
      description: |
        Upload and validate a CSV file for bulk user import. Returns a row-by-row report with
        a verdict per row (`valid` / `error` / `warning` / `ambiguous`), separating blocking
        `errors[]` from non-blocking `warnings[]`. Validated data is stored in a temporary
        session (30 min TTL) keyed by `import_id`, which must be passed to
        `/users/import/confirm` to actually create or update the users.

        **CSV format**

        - Columns (in any order): `email`, `name`, `phone`, `company_name`, `roles`.
        - Required: `email`, `name`, `company_name`, `roles`. `phone` is optional.
        - `company_name` is the visible name of the user's organization (matched against
          distributors/resellers/customers in the caller's hierarchy).
        - `phone`, when present, must include the leading `+CC` country prefix
          (e.g. `+39 333 1234567`). Bare local numbers without `+CC` are rejected
          with `invalid_format` at validate time. Phone uniqueness against existing
          users is also checked (`already_used`).
        - `roles` is a semicolon-separated list of role names (e.g. `Admin;Support`); names are
          resolved against the in-memory role cache.
        - `company_name` is matched case-insensitively against the caller's hierarchy.
          If multiple organizations share that name the row is marked `ambiguous` and the
          response includes the candidates — the caller picks one in `resolutions` at confirm time.
        - The first data row is row `2` (the header row is row `1`).
        - Standard CSV (RFC 4180) — fields containing commas, quotes or newlines must be
          double-quoted (`"value, with comma"`). Spreadsheet tools auto-quote on save.

        **Row outcomes**

        | status | What it means | Confirm action |
        |--------|---------------|----------------|
        | `valid` | All checks passed | CREATE |
        | `error` | At least one blocking error in `errors[]` (`required`, `invalid_format`, `duplicate_in_csv`, `not_found`, `unknown`, `archived`, `already_used`, …) | always skipped |
        | `warning` | `email` already exists in DB (in `warnings[]`) | UPDATE if `override: true`, else skipped |
        | `ambiguous` | Organization name matches multiple orgs | CREATE with chosen org if `resolutions[row]` is set, else skipped |

        Errors and warnings can coexist on the same row; status precedence is `error` > `ambiguous` > `warning` > `valid`.

        **Limits** — max 10 MB, max 1000 rows. Larger files return `400`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file to validate
      responses:
        '200':
          description: Validation report
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "users import validated"
                  data:
                    $ref: '#/components/schemas/ImportValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /users/import/confirm:
    post:
      operationId: confirmUsersImport
      tags:
        - Backend - Users Import/Export
      summary: /users/import/confirm - Execute validated user import
      description: |
        Confirm and execute a previously validated user import. Reuses the same pipelines as
        `POST /users` (CREATE) and `PUT /users/{id}` (UPDATE) for each row, so caller permissions
        are enforced per-row.

        **Inputs**

        - `import_id` — from the `/validate` response. Must still be valid (sessions expire after 30 min).
        - `override` — global flag. When `true`, every row with status `warning` (the user
          already exists, matched by email) is UPDATEd with the CSV values. When omitted/false,
          warning rows are skipped.
        - `resolutions` — required for any row with status `ambiguous` that you want to import;
          keyed by row number as a string, value is `{ organization_id }` picked from `candidates[]`.

        **Behaviour per row status**

        | status | `override` false | `override` true |
        |--------|------------------|------------------|
        | `valid` | CREATE | CREATE |
        | `error` | skipped (`reason: error`) | skipped (`reason: error`) |
        | `warning` | skipped (`reason: warning_not_overridden`) | UPDATE — `name`, `phone`, `company_name`, `roles` overwritten from CSV (`email` is the lookup key, never changed) |
        | `ambiguous` (no resolution) | skipped (`reason: ambiguous_unresolved`) | same |
        | `ambiguous` (resolution provided) | CREATE with chosen org | same |

        **RBAC for override**

        Updating an existing user requires the caller to have permission on the user's *current*
        organization (their hierarchy must include the target user's org). Organization changes
        ("moves") via override are allowed because the destination org has already been resolved
        against the caller's hierarchy at validate time. Per-row failures (status `failed`) are
        emitted when the caller cannot manage the existing user.

        **Atomicity** — non-atomic: failures during creation/update (Logto rate limits, RBAC
        denials) are reported per-row; rows that succeeded before the failure are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportConfirmRequest'
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "users imported successfully"
                  data:
                    $ref: '#/components/schemas/ImportConfirmResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # THIRD-PARTY APPLICATIONS (from Logto)
  # ===========================================================================
  /third-party-applications:
    get:
      operationId: getThirdPartyApplications
      tags:
        - Backend - Metadata
      summary: /third-party-applications - Get third-party applications
      description: Get third-party applications filtered by user's organization membership, organization roles, and user roles
      responses:
        '200':
          description: Third-party applications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "third-party applications retrieved successfully"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ThirdPartyApplication'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Failed to fetch applications from Logto
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ===========================================================================
  # AUTHENTICATION
  # ===========================================================================
  /auth/exchange:
    post:
      operationId: exchangeToken
      tags:
        - Backend - Authentication
      summary: /auth/exchange - Exchange Logto token for custom JWT
      description: Exchange a Logto access token for a custom JWT with embedded permissions
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenExchangeRequest'
      responses:
        '200':
          description: Token exchange successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "token exchange successful"
                  data:
                    $ref: '#/components/schemas/AuthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ===========================================================================
  # USER PROFILE (ME)
  # ===========================================================================
  /me:
    get:
      operationId: getMe
      tags:
        - Backend - Me
      summary: /me - Get current user information
      description: Get current authenticated user's profile and permissions
      responses:
        '200':
          description: User information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user information retrieved successfully"
                  data:
                    $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /me/change-password:
    post:
      operationId: changeMyPassword
      tags:
        - Backend - Me
      summary: /me/change-password - Change current user password
      description: Allow the current authenticated user to change their own password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "password changed successfully"
                  data:
                    type: object
                    nullable: true
                    example: null
        '400':
          description: Bad request - validation error for current password verification or new password requirements
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "validation failed"
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        enum: [validation_error]
                        example: "validation_error"
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              description: Field name that failed validation
                              enum: [current_password, new_password]
                              example: "new_password"
                            message:
                              type: string
                              description: Validation error type
                              example: "min_length"
                            value:
                              type: string
                              description: Always empty for security (passwords not exposed)
                              example: ""
                        example:
                          - key: "current_password"
                            message: "incorrect_password"
                            value: ""
                          - key: "new_password"
                            message: "min_length"
                            value: ""
                          - key: "new_password"
                            message: "missing_uppercase"
                            value: ""
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: "invalid token"
                  data:
                    type: object
                    nullable: true
                    example: null
        '500':
          $ref: '#/components/responses/InternalServerError'

  /me/change-info:
    post:
      operationId: changeMyInfo
      tags:
        - Backend - Me
      summary: /me/change-info - Change current user information
      description: Allow the current authenticated user to change their name, email, and phone number. Name and email cannot be empty if provided.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeInfoRequest'
      responses:
        '200':
          description: User information changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user information changed successfully"
                  data:
                    type: object
                    nullable: true
                    example: null
        '400':
          description: Bad request - validation error for name or phone
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "validation failed"
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        enum: [validation_error]
                        example: "validation_error"
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              description: Field name that failed validation
                              enum: [name, email, phone]
                              example: "name"
                            message:
                              type: string
                              description: Validation error message
                              enum: ["name cannot be empty", "email cannot be empty", "invalid email format", "invalid phone format"]
                              example: "name cannot be empty"
                            value:
                              type: string
                              description: Value that failed validation
                              example: ""
                        example:
                          - key: "name"
                            message: "name cannot be empty"
                            value: ""
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: "invalid token"
                  data:
                    type: object
                    nullable: true
                    example: null
        '500':
          $ref: '#/components/responses/InternalServerError'

  /me/avatar:
    put:
      operationId: uploadMyAvatar
      tags:
        - Backend - Me
      summary: /me/avatar - Upload current user avatar
      description: |
        Upload a profile image for the current authenticated user.
        The image is validated, resized to 256x256 pixels if larger, re-encoded as PNG, and stored in the database.
        The avatar URL is automatically synced to the user's Logto profile.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - avatar
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Avatar image file (PNG, JPEG, or WebP, max 500KB, resized to 256x256)
      responses:
        '200':
          description: Avatar uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "avatar uploaded successfully"
                  data:
                    type: object
                    properties:
                      avatar_url:
                        type: string
                        description: Public URL of the uploaded avatar
                        example: "https://my.nethesis.it/api/public/users/jf584cz36kce/avatar"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteMyAvatar
      tags:
        - Backend - Me
      summary: /me/avatar - Delete current user avatar
      description: Remove the profile image for the current authenticated user. Clears the avatar from the database and the Logto profile.
      responses:
        '200':
          description: Avatar deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "avatar deleted successfully"
                  data:
                    type: object
                    nullable: true
                    example: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /public/users/{id}/avatar:
    get:
      operationId: getPublicAvatar
      tags:
        - Backend - Public
      summary: /public/users/{id}/avatar - Get user avatar image
      description: Serves a user's avatar image as binary data. This endpoint is public and requires no authentication. Returns the image with appropriate Content-Type header and browser caching headers.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: User Logto ID or local database ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Avatar image binary
          headers:
            Cache-Control:
              schema:
                type: string
                example: "public, max-age=3600"
          content:
            image/png:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'

  /auth/refresh:
    post:
      operationId: refreshToken
      tags:
        - Backend - Authentication
      summary: /auth/refresh - Refresh access token
      description: Get new access token using refresh token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRefreshRequest'
      responses:
        '200':
          description: Token refresh successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "token refresh successful"
                  data:
                    $ref: '#/components/schemas/AuthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /auth/logout:
    post:
      operationId: logout
      tags:
        - Backend - Authentication
      summary: /auth/logout - Logout user
      description: Invalidate user's access token and refresh token (blacklist tokens)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Refresh token to blacklist
                  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
              required:
                - refresh_token
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "logout successful"
                  data:
                    type: object
                    nullable: true
                    example: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ===========================================================================
  # CONSENT-BASED IMPERSONATION SYSTEM
  # ===========================================================================

  /impersonate/consent:
    post:
      operationId: enableImpersonationConsent
      tags:
        - Backend - Impersonation
      summary: /impersonate/consent - Enable impersonation consent
      description: |
        Allows a user to enable consent for being impersonated by authorized users (Super Admin role or Owner organization users).
        This is a **privacy-friendly** approach where users explicitly control
        if and for how long they can be impersonated.

        **Key Features:**
        - User controls their own impersonation consent
        - Custom duration (1-168 hours)
        - Only active while consent is valid
        - Complete audit trail of all impersonation activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                duration_hours:
                  type: integer
                  minimum: 1
                  maximum: 168
                  default: 1
                  description: How many hours the consent should be active (max 1 week, defaults to 1 hour)
                  example: 24
      responses:
        '200':
          description: Impersonation consent enabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "impersonation consent enabled successfully"
                  data:
                    type: object
                    properties:
                      consent:
                        $ref: '#/components/schemas/ImpersonationConsent'
        '400':
          description: Bad request (invalid duration)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: "Duration must be between 1 and 168 hours"
        '401':
          $ref: '#/components/responses/Unauthorized'

    get:
      operationId: getImpersonationConsentStatus
      tags:
        - Backend - Impersonation
      summary: /impersonate/consent - Get impersonation consent status
      description: |
        Retrieves the current impersonation consent status for the authenticated user.
        Shows if consent is active, when it expires, and other consent details.
      responses:
        '200':
          description: Consent status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "consent status retrieved successfully"
                  data:
                    type: object
                    properties:
                      consent:
                        allOf:
                          - $ref: '#/components/schemas/ImpersonationConsent'
                        type: object
                        nullable: true
                        description: Consent details (null if no active consent)
        '401':
          $ref: '#/components/responses/Unauthorized'

    delete:
      operationId: disableImpersonationConsent
      tags:
        - Backend - Impersonation
      summary: /impersonate/consent - Disable impersonation consent
      description: |
        Disables all active impersonation consent for the authenticated user.
        This prevents any future impersonation until consent is re-enabled.
      responses:
        '200':
          description: Impersonation consent disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "impersonation consent disabled successfully"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'

  /impersonate:
    post:
      operationId: impersonateUserWithConsent
      tags:
        - Backend - Impersonation
      summary: /impersonate - Start impersonation (permission-based access)
      description: |
        Allows users with `impersonate:users` permission (Super Admin role) or Owner organization role
        to impersonate another user, but only if that user has active consent enabled.
        The impersonation token duration will match the user's consent settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: Logto ID of the user to impersonate
                  example: "jf584cz36kce"
              required:
                - user_id
      responses:
        '200':
          description: Impersonation started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "impersonation started successfully"
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: Impersonation JWT token with custom duration
                        example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                      expires_in:
                        type: integer
                        description: Token expiration time in seconds (matches user consent)
                        example: 86400
                      session_id:
                        type: string
                        description: Unique session ID for audit tracking
                        example: "session-uuid-here"
                      is_impersonating:
                        type: boolean
                        description: Flag indicating impersonation is active
                        example: true
                      impersonated_user:
                        $ref: '#/components/schemas/User'
                      impersonator:
                        $ref: '#/components/schemas/User'
        '400':
          description: Bad request (cannot impersonate yourself, user not found, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                self_impersonation:
                  summary: Cannot impersonate yourself
                  value:
                    code: 400
                    message: "Cannot impersonate yourself"
                user_not_found:
                  summary: Target user not found
                  value:
                    code: 400
                    message: "Target user not found or inaccessible"
                no_consent:
                  summary: User has no active consent
                  value:
                    code: 400
                    message: "Target user has not provided consent for impersonation or consent has expired"
        '403':
          description: Forbidden (insufficient permissions for impersonation, or already impersonating)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_permissions:
                  summary: User without impersonation permissions attempted impersonation
                  value:
                    code: 403
                    message: "Insufficient permissions to impersonate users"
                already_impersonating:
                  summary: Cannot impersonate while already impersonating
                  value:
                    code: 403
                    message: "Cannot impersonate while already impersonating another user. Exit current impersonation first."
        '401':
          $ref: '#/components/responses/Unauthorized'

    delete:
      operationId: exitImpersonationWithAudit
      tags:
        - Backend - Impersonation
      summary: /impersonate - Exit impersonation mode
      description: |
        Allows user to exit impersonation mode and return to their original account.
        This endpoint can only be called with an active impersonation token.
        Returns fresh tokens for the original user and completes the audit session.
      responses:
        '200':
          description: Impersonation ended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "impersonation ended successfully"
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: New JWT token for original user (24-hour expiration)
                        example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                      refresh_token:
                        type: string
                        description: New refresh token for original user
                        example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                      expires_in:
                        type: integer
                        description: Token expiration time in seconds (86400 = 24 hours)
                        example: 86400
        '400':
          description: Bad request (not currently impersonating)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: "Not currently impersonating a user"
        '401':
          $ref: '#/components/responses/Unauthorized'

  /impersonate/status:
    get:
      operationId: getImpersonationStatus
      tags:
        - Backend - Impersonation
      summary: /impersonate/status - Check current impersonation status
      description: |
        Checks if the current user has an active impersonation session.

        **Works with both token types:**
        - **Impersonation token**: Returns session details from the token
        - **Regular token**: Checks Redis for active session and returns a new impersonation token if found

        **Use case for regular token:**
        After a page refresh, the frontend loses the impersonation token but calls `/auth/exchange`
        to get a regular token. This endpoint allows the frontend to check if there's an active
        impersonation session and receive a new impersonation token to continue the session.

        **Response when impersonating:**
        - `is_impersonating`: true
        - `token`: New impersonation JWT token (with remaining duration)
        - `expires_in`: Remaining seconds until expiration
        - `session_id`: Session ID for audit tracking
        - `impersonated_user`: Details of the user being impersonated
        - `impersonator`: Details of the user doing the impersonation
        - `expires_at`: Session expiration timestamp
        - `created_at`: Session creation timestamp

        **Response when not impersonating:**
        - `is_impersonating`: false
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    enum: ["currently impersonating", "not currently impersonating"]
                    example: "currently impersonating"
                  data:
                    type: object
                    properties:
                      is_impersonating:
                        type: boolean
                        description: Whether the user is currently impersonating someone
                        example: true
                      token:
                        type: string
                        description: Impersonation JWT token (only present when is_impersonating is true)
                        example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                      expires_in:
                        type: integer
                        description: Remaining seconds until token expiration (only present when is_impersonating is true)
                        example: 3540
                      session_id:
                        type: string
                        description: Session ID for audit tracking (only present when is_impersonating is true)
                        example: "session-uuid-here"
                      impersonated_user:
                        description: Details of the user being impersonated (only present when is_impersonating is true)
                        allOf:
                          - $ref: '#/components/schemas/User'
                      impersonator:
                        description: Details of the user doing the impersonation (only present when is_impersonating is true)
                        allOf:
                          - $ref: '#/components/schemas/User'
                      expires_at:
                        type: string
                        format: date-time
                        description: Session expiration timestamp (only present when is_impersonating is true)
                        example: "2025-09-29T17:33:59Z"
                      created_at:
                        type: string
                        format: date-time
                        description: Session creation timestamp (only present when is_impersonating is true)
                        example: "2025-09-29T16:33:59Z"
              examples:
                impersonating:
                  summary: Currently impersonating
                  value:
                    code: 200
                    message: "currently impersonating"
                    data:
                      is_impersonating: true
                      token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                      expires_in: 3540
                      session_id: "d7734c1e-bed3-4350-8992-a5e09d4d253f"
                      impersonated_user:
                        id: "d1e17b87-11ce-4e74-a9f8-34d9638135f1"
                        username: "edoardo_spadoni"
                        email: "edoardo.spadoni@nethesis.it"
                        name: "Edoardo Support"
                        org_role: "Reseller"
                      impersonator:
                        id: "c5054f56-3005-43c2-a237-07aa44e1551c"
                        username: "owner"
                        email: "owner@example.com"
                        name: "Company Owner"
                        org_role: "Owner"
                      expires_at: "2025-09-29T17:33:59Z"
                      created_at: "2025-09-29T16:33:59Z"
                not_impersonating:
                  summary: Not impersonating
                  value:
                    code: 200
                    message: "not currently impersonating"
                    data:
                      is_impersonating: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error (failed to check session or generate token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                session_check_failed:
                  summary: Failed to check for active session
                  value:
                    code: 500
                    message: "failed to check impersonation status"
                token_generation_failed:
                  summary: Failed to generate impersonation token
                  value:
                    code: 500
                    message: "failed to generate impersonation token"

  /impersonate/sessions:
    get:
      operationId: getImpersonationSessions
      tags:
        - Backend - Impersonation Sessions
      summary: /impersonate/sessions - List impersonation sessions
      description: |
        Retrieves all impersonation sessions for the current user. Sessions are grouped
        by session_id and show start/end times, duration, and action count. This endpoint
        should be used first to get session overview, then use /impersonate/audit/{session_id}
        to get detailed audit logs for specific sessions.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Sessions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "sessions retrieved successfully"
                  data:
                    type: object
                    properties:
                      sessions:
                        type: array
                        items:
                          $ref: '#/components/schemas/ImpersonationSession'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /impersonate/sessions/{session_id}:
    get:
      operationId: getImpersonationSession
      tags:
        - Backend - Impersonation Sessions
      summary: /impersonate/sessions/{session_id} - Get details for specific session
      description: |
        Retrieves details for a specific impersonation session. Users can only
        view sessions where they were impersonated. The session must belong to
        the requesting user.
      parameters:
        - name: session_id
          in: path
          description: Impersonation session ID
          required: true
          schema:
            type: string
          example: "sess_abc123def456"
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Session details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "session details retrieved successfully"
                  data:
                    type: object
                    properties:
                      session:
                        $ref: '#/components/schemas/ImpersonationSession'
        '400':
          description: Missing or invalid session_id parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: "session_id parameter is required"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 404
                message: "session not found"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /impersonate/sessions/{session_id}/audit:
    get:
      operationId: getSessionAudit
      tags:
        - Backend - Impersonation Sessions
      summary: /impersonate/sessions/{session_id}/audit - Get audit logs for specific session
      description: |
        Retrieves detailed audit logs for a specific impersonation session. Users can only
        view audit logs for their own sessions (when they were impersonated). The session
        must belong to the requesting user.
      parameters:
        - name: session_id
          in: path
          description: Impersonation session ID
          required: true
          schema:
            type: string
          example: "sess_abc123def456"
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Session audit logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "session audit retrieved successfully"
                  data:
                    type: object
                    properties:
                      session_id:
                        type: string
                        description: Session ID
                        example: "sess_abc123def456"
                      entries:
                        type: array
                        items:
                          $ref: '#/components/schemas/ImpersonationAuditEntry'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '400':
          description: Missing or invalid session_id parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: "session_id parameter is required"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Session not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 404
                message: "session not found or access denied"
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ===========================================================================
  # BUSINESS HIERARCHY - CUSTOMERS
  # ===========================================================================
  /customers:
    get:
      operationId: getCustomers
      tags:
        - Backend - Customers
      summary: /customers - List customers
      description: Get paginated list of customers (Owner + Distributor + Reseller)
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/CustomerSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/OrganizationStatusFilterParam'
      responses:
        '200':
          description: Customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customers retrieved successfully"
                  data:
                    type: object
                    properties:
                      customers:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationWithStats'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      operationId: createCustomer
      tags:
        - Backend - Customers
      summary: /customers - Create customer
      description: Create a new customer organization (Owner + Distributor + Reseller)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "customer created successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /customers/{id}:
    get:
      operationId: getCustomerById
      tags:
        - Backend - Customers
      summary: /customers/{id} - Get single customer
      description: Get a specific customer by ID (Owner + Distributor + Reseller)
      parameters:
        - name: id
          in: path
          required: true
          description: Customer Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer retrieved successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id} - Update customer
      description: Update a customer organization (Owner + Distributor + Reseller)
      parameters:
        - name: id
          in: path
          required: true
          description: Customer Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer updated successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

    delete:
      operationId: deleteCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id} - Delete customer
      description: Delete a customer organization (Owner + Distributor + Reseller)
      parameters:
        - name: id
          in: path
          required: true
          description: Customer Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Customer deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer deleted successfully"
                  data:
                    type: object
                    properties:
                      deleted_systems_count:
                        type: integer
                        description: Number of systems cascade soft-deleted for this customer
                        example: 2
                      deleted_users_count:
                        type: integer
                        description: Number of users cascade soft-deleted for this customer
                        example: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/{id}/stats:
    get:
      operationId: getCustomerStats
      tags:
        - Backend - Customers
      summary: /customers/{id}/stats - Get customer statistics
      description: Get users, systems and applications count for a specific customer (Owner + Distributor + Reseller + own Customer)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Customer Logto ID
      responses:
        '200':
          description: Customer stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer stats retrieved successfully"
                  data:
                    $ref: '#/components/schemas/CustomerStats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/{id}/suspend:
    patch:
      operationId: suspendCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id}/suspend - Suspend customer
      description: Suspend a customer and all its users (cascade suspension). Owner, Distributor, and Reseller (hierarchical) can suspend.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Customer Logto ID
      responses:
        '200':
          description: Customer suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer suspended successfully"
                  data:
                    type: object
                    properties:
                      customer:
                        $ref: '#/components/schemas/Organization'
                      suspended_users_count:
                        type: integer
                        example: 5
                        description: Number of users that were cascade-suspended
                      suspended_systems_count:
                        type: integer
                        example: 3
                        description: Number of systems that were cascade-suspended
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/{id}/reactivate:
    patch:
      operationId: reactivateCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id}/reactivate - Reactivate customer
      description: Reactivate a suspended customer and all its cascade-suspended users. Owner, Distributor, and Reseller (hierarchical) can reactivate.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Customer Logto ID
      responses:
        '200':
          description: Customer reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer reactivated successfully"
                  data:
                    type: object
                    properties:
                      customer:
                        $ref: '#/components/schemas/Organization'
                      reactivated_users_count:
                        type: integer
                        example: 5
                        description: Number of users that were cascade-reactivated
                      reactivated_systems_count:
                        type: integer
                        example: 3
                        description: Number of systems that were cascade-reactivated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/{id}/restore:
    patch:
      operationId: restoreCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id}/restore - Restore soft-deleted customer
      description: Restore a soft-deleted customer (requires manage:customers permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Customer Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Customer restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer restored successfully"
                  data:
                    type: object
                    properties:
                      restored_systems_count:
                        type: integer
                        description: Number of systems cascade restored for this customer
                        example: 2
                      restored_users_count:
                        type: integer
                        description: Number of users cascade restored for this customer
                        example: 3
        '400':
          description: Bad request - Customer is not deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "customer is not deleted"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/{id}/destroy:
    delete:
      operationId: destroyCustomer
      tags:
        - Backend - Customers
      summary: /customers/{id}/destroy - Permanently delete customer
      description: Permanently delete a customer organization (requires destroy:customers permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Customer Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Customer permanently destroyed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customer permanently destroyed"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /customers/totals:
    get:
      operationId: getCustomersTotals
      tags:
        - Backend - Customers Stats
      summary: /customers/totals - Get customers totals
      description: Get total count of customers accessible to the user (Owner + Distributor + Reseller)
      responses:
        '200':
          description: Customers totals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customers totals retrieved"
                  data:
                    $ref: '#/components/schemas/Totals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /customers/trend:
    get:
      operationId: getCustomersTrend
      tags:
        - Backend - Customers Stats
      summary: /customers/trend - Get customers trend data
      description: Get trend analysis of customers over time with cumulative counts (Owner + Distributor + Reseller)
      parameters:
        - $ref: '#/components/parameters/TrendPeriodParam'
      responses:
        '200':
          description: Customers trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customers trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /customers/export:
    get:
      operationId: exportCustomers
      tags:
        - Backend - Customers Import/Export
      summary: /customers/export - Export customers to CSV or PDF
      description: Export customers to CSV or PDF format with applied filters (max 10,000 customers)
      parameters:
        - name: format
          in: query
          required: true
          description: Export format (csv or pdf)
          schema:
            type: string
            enum: [csv, pdf]
            example: "csv"
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/CustomerSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
      responses:
        '200':
          description: Customers exported successfully
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # BUSINESS HIERARCHY - DISTRIBUTORS
  # ===========================================================================
  /distributors:
    get:
      operationId: getDistributors
      tags:
        - Backend - Distributors
      summary: /distributors - List distributors
      description: Get paginated list of distributors (Owner only)
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/DistributorSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/OrganizationStatusFilterParam'
      responses:
        '200':
          description: Distributors retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributors retrieved successfully"
                  data:
                    type: object
                    properties:
                      distributors:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationWithStats'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      operationId: createDistributor
      tags:
        - Backend - Distributors
      summary: /distributors - Create distributor
      description: Create a new distributor organization (Owner only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '201':
          description: Distributor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "distributor created successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /distributors/{id}:
    get:
      operationId: getDistributorById
      tags:
        - Backend - Distributors
      summary: /distributors/{id} - Get single distributor
      description: Get a specific distributor by ID (Owner only)
      parameters:
        - name: id
          in: path
          required: true
          description: Distributor Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Distributor retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor retrieved successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id} - Update distributor
      description: Update a distributor organization (Owner only)
      parameters:
        - name: id
          in: path
          required: true
          description: Distributor Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '200':
          description: Distributor updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor updated successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

    delete:
      operationId: deleteDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id} - Delete distributor
      description: Delete a distributor organization (Owner only)
      parameters:
        - name: id
          in: path
          required: true
          description: Distributor Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Distributor deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor deleted successfully"
                  data:
                    type: object
                    properties:
                      deleted_systems_count:
                        type: integer
                        description: Number of systems cascade soft-deleted across the distributor hierarchy
                        example: 5
                      deleted_users_count:
                        type: integer
                        description: Number of users cascade soft-deleted across the distributor hierarchy
                        example: 12
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/{id}/stats:
    get:
      operationId: getDistributorStats
      tags:
        - Backend - Distributors
      summary: /distributors/{id}/stats - Get distributor statistics
      description: Get users, systems, resellers and customers count for a specific distributor (Owner only)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Distributor Logto ID
      responses:
        '200':
          description: Distributor stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor stats retrieved successfully"
                  data:
                    $ref: '#/components/schemas/DistributorStats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/{id}/suspend:
    patch:
      operationId: suspendDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id}/suspend - Suspend distributor
      description: Suspend a distributor and all its users (cascade suspension). Owner only.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Distributor Logto ID
      responses:
        '200':
          description: Distributor suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor suspended successfully"
                  data:
                    type: object
                    properties:
                      distributor:
                        $ref: '#/components/schemas/Organization'
                      suspended_resellers_count:
                        type: integer
                        example: 3
                        description: Number of resellers that were cascade-suspended
                      suspended_customers_count:
                        type: integer
                        example: 10
                        description: Number of customers that were cascade-suspended
                      suspended_users_count:
                        type: integer
                        example: 25
                        description: Number of users that were cascade-suspended
                      suspended_systems_count:
                        type: integer
                        example: 15
                        description: Number of systems that were cascade-suspended
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/{id}/reactivate:
    patch:
      operationId: reactivateDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id}/reactivate - Reactivate distributor
      description: Reactivate a suspended distributor and all its cascade-suspended users. Owner only.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Distributor Logto ID
      responses:
        '200':
          description: Distributor reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor reactivated successfully"
                  data:
                    type: object
                    properties:
                      distributor:
                        $ref: '#/components/schemas/Organization'
                      reactivated_resellers_count:
                        type: integer
                        example: 3
                        description: Number of resellers that were cascade-reactivated
                      reactivated_customers_count:
                        type: integer
                        example: 10
                        description: Number of customers that were cascade-reactivated
                      reactivated_users_count:
                        type: integer
                        example: 25
                        description: Number of users that were cascade-reactivated
                      reactivated_systems_count:
                        type: integer
                        example: 15
                        description: Number of systems that were cascade-reactivated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/{id}/restore:
    patch:
      operationId: restoreDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id}/restore - Restore soft-deleted distributor
      description: Restore a soft-deleted distributor (requires manage:distributors permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Distributor Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Distributor restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor restored successfully"
                  data:
                    type: object
                    properties:
                      restored_systems_count:
                        type: integer
                        description: Number of systems cascade restored across the distributor hierarchy
                        example: 5
                      restored_users_count:
                        type: integer
                        description: Number of users cascade restored across the distributor hierarchy
                        example: 12
        '400':
          description: Bad request - Distributor is not deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "distributor is not deleted"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/{id}/destroy:
    delete:
      operationId: destroyDistributor
      tags:
        - Backend - Distributors
      summary: /distributors/{id}/destroy - Permanently delete distributor
      description: Permanently delete a distributor organization (requires destroy:distributors permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Distributor Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Distributor permanently destroyed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributor permanently destroyed"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /distributors/totals:
    get:
      operationId: getDistributorsTotals
      tags:
        - Backend - Distributors Stats
      summary: /distributors/totals - Get distributors totals
      description: Get total count of distributors accessible to the user (Owner only)
      responses:
        '200':
          description: Distributors totals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributors totals retrieved"
                  data:
                    $ref: '#/components/schemas/Totals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /distributors/trend:
    get:
      operationId: getDistributorsTrend
      tags:
        - Backend - Distributors Stats
      summary: /distributors/trend - Get distributors trend data
      description: Get trend analysis of distributors over time with cumulative counts (Owner only)
      parameters:
        - $ref: '#/components/parameters/TrendPeriodParam'
      responses:
        '200':
          description: Distributors trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributors trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /distributors/export:
    get:
      operationId: exportDistributors
      tags:
        - Backend - Distributors Import/Export
      summary: /distributors/export - Export distributors to CSV or PDF
      description: Export distributors to CSV or PDF format with applied filters (max 10,000 distributors)
      parameters:
        - name: format
          in: query
          required: true
          description: Export format (csv or pdf)
          schema:
            type: string
            enum: [csv, pdf]
            example: "csv"
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/DistributorSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
      responses:
        '200':
          description: Distributors exported successfully
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # DISTRIBUTORS IMPORT
  # ===========================================================================
  /distributors/import/template:
    get:
      operationId: getDistributorsImportTemplate
      tags:
        - Backend - Distributors Import/Export
      summary: /distributors/import/template - Download CSV import template
      description: |
        Download a UTF-8 CSV file pre-populated with the expected header row and a few example
        data rows for the distributor import flow. Columns: `company_name`, `description`, `vat_number`,
        `address`, `city`, `main_contact`, `email`, `phone`, `language`, `notes`. Sent as a
        `text/csv` attachment with `Content-Disposition: attachment; filename="distributors_import_template.csv"`.
      responses:
        '200':
          description: CSV template downloaded
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /distributors/import/validate:
    post:
      operationId: validateDistributorsImport
      tags:
        - Backend - Distributors Import/Export
      summary: /distributors/import/validate - Validate CSV for distributor import
      description: |
        Upload and validate a CSV file for bulk distributor import. Returns a row-by-row report
        with a verdict per row (`valid` / `error` / `warning`), separating blocking `errors[]`
        from non-blocking `warnings[]`. Validated data is stored in a temporary session
        (30 min TTL) keyed by `import_id`, which must be passed to `/distributors/import/confirm`
        to actually create or update the distributors.

        **CSV format**

        - Columns (in any order): `company_name`, `description`, `vat_number`, `address`, `city`,
          `main_contact`, `email`, `phone`, `language`, `notes`.
        - Required: `company_name`, `vat_number`. All other columns are optional.
        - `phone`, when present, must include the leading `+CC` country prefix
          (e.g. `+39 02 1234567`). Bare local numbers are rejected with `invalid_format`.
        - `language` accepts `it` or `en` (defaults to `it` when empty).
        - The first data row is row `2`.
        - Standard CSV (RFC 4180) — fields containing commas, quotes or newlines must be
          double-quoted (`"note, with comma"`). Spreadsheet tools auto-quote on save.

        **Row outcomes**

        | status | What it means | Confirm action |
        |--------|---------------|----------------|
        | `valid` | All checks passed | CREATE |
        | `error` | At least one blocking error in `errors[]` (`required`, `invalid_format`, `too_long`, `duplicate_in_csv`, `archived`, …) | always skipped |
        | `warning` | A distributor with the same `vat` already exists in the database (in `warnings[]`) | UPDATE if `override: true`, else skipped |

        Distributor imports cannot produce `ambiguous` rows — that status only applies to user imports.

        **Limits** — max 10 MB, max 1000 rows. Larger files return `400`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Validation report
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributors import validated"
                  data:
                    $ref: '#/components/schemas/ImportValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /distributors/import/confirm:
    post:
      operationId: confirmDistributorsImport
      tags:
        - Backend - Distributors Import/Export
      summary: /distributors/import/confirm - Execute validated distributor import
      description: |
        Confirm and execute a previously validated distributor import. Reuses `POST /distributors`
        (CREATE) and `PUT /distributors/{id}` (UPDATE) for each row.

        **Inputs**

        - `import_id` — from the `/validate` response. Must still be valid (sessions expire after 30 min).
        - `override` — global flag. When `true`, every row with status `warning` (a
          distributor with the same VAT already exists in the DB) is UPDATEd with the CSV
          values; name, description, address, city, main_contact, email, phone, language,
          notes all get overwritten. When omitted/false, warning rows are skipped.
        - `resolutions` — not applicable to distributors.

        **Behaviour per row status**

        | status | `override` false | `override` true |
        |--------|------------------|------------------|
        | `valid` | CREATE | CREATE |
        | `error` | skipped (`reason: error`) | skipped (`reason: error`) |
        | `warning` | skipped (`reason: warning_not_overridden`) | UPDATE — all custom_data fields overwritten from CSV (name is the lookup key, never changed) |

        **Atomicity** — non-atomic: failures during creation/update are reported per-row;
        rows that succeeded before the failure are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportConfirmRequest'
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "distributors imported successfully"
                  data:
                    $ref: '#/components/schemas/ImportConfirmResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # RESELLERS IMPORT
  # ===========================================================================
  /resellers/import/template:
    get:
      operationId: getResellersImportTemplate
      tags:
        - Backend - Resellers Import/Export
      summary: /resellers/import/template - Download CSV import template
      description: |
        Download a UTF-8 CSV file pre-populated with the expected header row and a few example
        data rows for the reseller import flow. Columns: `company_name`, `description`, `vat_number`,
        `address`, `city`, `main_contact`, `email`, `phone`, `language`, `notes`. Sent as a
        `text/csv` attachment with `Content-Disposition: attachment; filename="resellers_import_template.csv"`.
      responses:
        '200':
          description: CSV template downloaded
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /resellers/import/validate:
    post:
      operationId: validateResellersImport
      tags:
        - Backend - Resellers Import/Export
      summary: /resellers/import/validate - Validate CSV for reseller import
      description: |
        Upload and validate a CSV file for bulk reseller import. Returns a row-by-row report
        with a verdict per row (`valid` / `error` / `warning`), separating blocking `errors[]`
        from non-blocking `warnings[]`. Validated data is stored in a temporary session
        (30 min TTL) keyed by `import_id`, which must be passed to `/resellers/import/confirm`
        to actually create or update the resellers.

        **CSV format**

        - Columns (in any order): `company_name`, `description`, `vat_number`, `address`, `city`,
          `main_contact`, `email`, `phone`, `language`, `notes`.
        - Required: `company_name`, `vat_number`. All other columns are optional.
        - `phone`, when present, must include the leading `+CC` country prefix
          (e.g. `+39 02 1234567`). Bare local numbers are rejected with `invalid_format`.
        - `language` accepts `it` or `en` (defaults to `it` when empty).
        - The first data row is row `2`.
        - Standard CSV (RFC 4180) — fields containing commas, quotes or newlines must be
          double-quoted (`"note, with comma"`). Spreadsheet tools auto-quote on save.

        **Row outcomes**

        | status | What it means | Confirm action |
        |--------|---------------|----------------|
        | `valid` | All checks passed | CREATE |
        | `error` | At least one blocking error in `errors[]` (`required`, `invalid_format`, `too_long`, `duplicate_in_csv`, `archived`, …) | always skipped |
        | `warning` | A reseller with the same `vat` already exists in the database (in `warnings[]`) | UPDATE if `override: true`, else skipped |

        Reseller imports cannot produce `ambiguous` rows — that status only applies to user imports.

        **Limits** — max 10 MB, max 1000 rows. Larger files return `400`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Validation report
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "resellers import validated"
                  data:
                    $ref: '#/components/schemas/ImportValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /resellers/import/confirm:
    post:
      operationId: confirmResellersImport
      tags:
        - Backend - Resellers Import/Export
      summary: /resellers/import/confirm - Execute validated reseller import
      description: |
        Confirm and execute a previously validated reseller import. Reuses `POST /resellers`
        (CREATE) and `PUT /resellers/{id}` (UPDATE) for each row.

        **Inputs**

        - `import_id` — from the `/validate` response. Must still be valid (sessions expire after 30 min).
        - `override` — global flag. When `true`, every row with status `warning` (a reseller
          with the same VAT already exists in the DB) is UPDATEd with the CSV values. When
          omitted/false, warning rows are skipped.
        - `resolutions` — not applicable to resellers.

        **Behaviour per row status**

        | status | `override` false | `override` true |
        |--------|------------------|------------------|
        | `valid` | CREATE | CREATE |
        | `error` | skipped (`reason: error`) | skipped (`reason: error`) |
        | `warning` | skipped (`reason: warning_not_overridden`) | UPDATE — all custom_data fields overwritten from CSV |

        **Atomicity** — non-atomic: failures during creation/update are reported per-row;
        rows that succeeded before the failure are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportConfirmRequest'
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "resellers imported successfully"
                  data:
                    $ref: '#/components/schemas/ImportConfirmResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # CUSTOMERS IMPORT
  # ===========================================================================
  /customers/import/template:
    get:
      operationId: getCustomersImportTemplate
      tags:
        - Backend - Customers Import/Export
      summary: /customers/import/template - Download CSV import template
      description: |
        Download a UTF-8 CSV file pre-populated with the expected header row and a few example
        data rows for the customer import flow. Columns: `company_name`, `description`, `vat_number`,
        `address`, `city`, `main_contact`, `email`, `phone`, `language`, `notes`. Sent as a
        `text/csv` attachment with `Content-Disposition: attachment; filename="customers_import_template.csv"`.
      responses:
        '200':
          description: CSV template downloaded
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /customers/import/validate:
    post:
      operationId: validateCustomersImport
      tags:
        - Backend - Customers Import/Export
      summary: /customers/import/validate - Validate CSV for customer import
      description: |
        Upload and validate a CSV file for bulk customer import. Returns a row-by-row report
        with a verdict per row (`valid` / `error` / `warning`), separating blocking `errors[]`
        from non-blocking `warnings[]`. Validated data is stored in a temporary session
        (30 min TTL) keyed by `import_id`, which must be passed to `/customers/import/confirm`
        to actually create or update the customers.

        **CSV format**

        - Columns (in any order): `company_name`, `description`, `vat_number`, `address`, `city`,
          `main_contact`, `email`, `phone`, `language`, `notes`.
        - Required: `company_name`, `vat_number`. All other columns are optional.
        - `phone`, when present, must include the leading `+CC` country prefix
          (e.g. `+39 02 1234567`). Bare local numbers are rejected with `invalid_format`.
        - `language` accepts `it` or `en` (defaults to `it` when empty).
        - The first data row is row `2`.
        - Standard CSV (RFC 4180) — fields containing commas, quotes or newlines must be
          double-quoted (`"note, with comma"`). Spreadsheet tools auto-quote on save.

        **Row outcomes**

        | status | What it means | Confirm action |
        |--------|---------------|----------------|
        | `valid` | All checks passed | CREATE |
        | `error` | At least one blocking error in `errors[]` (`required`, `invalid_format`, `too_long`, `duplicate_in_csv`, …) | always skipped |

        Customer imports never produce `warning`, `archived` or `ambiguous` rows. The DB
        does not enforce uniqueness on customer name or VAT, so every well-formed customer
        row is `valid` and creates a new record at confirm. The `override` flag is
        therefore a no-op for `/customers/import/confirm`.

        **Limits** — max 10 MB, max 1000 rows. Larger files return `400`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Validation report
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customers import validated"
                  data:
                    $ref: '#/components/schemas/ImportValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /customers/import/confirm:
    post:
      operationId: confirmCustomersImport
      tags:
        - Backend - Customers Import/Export
      summary: /customers/import/confirm - Execute validated customer import
      description: |
        Confirm and execute a previously validated customer import. Calls `POST /customers`
        (CREATE) for every `valid` row.

        **Inputs**

        - `import_id` — from the `/validate` response. Must still be valid (sessions expire after 30 min).
        - `override` — **no-op for customers**: validate never emits `warning` rows since the
          DB enforces no uniqueness on customer name or VAT, so there is nothing to UPDATE.
        - `resolutions` — not applicable to customers.

        **Behaviour per row status**

        | status | confirm action |
        |--------|----------------|
        | `valid` | CREATE |
        | `error` | skipped (`reason: error`) |

        **Atomicity** — non-atomic: failures during creation are reported per-row;
        rows that succeeded before the failure are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportConfirmRequest'
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "customers imported successfully"
                  data:
                    $ref: '#/components/schemas/ImportConfirmResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # HEALTH CHECK
  # ===========================================================================
  /health:
    get:
      operationId: getHealth
      tags:
        - Backend - Health
        - Collect - Health
      summary: /health - Health check
      description: Check if the service is healthy (available on both backend and collect servers)
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "service healthy"
                  data:
                    type: object
                    description: Health data (collect includes worker metrics)
                    nullable: true
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: "endpoint not found"
                  data:
                    type: object
                    nullable: true
                    example: null
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Service is unhealthy (collect service only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ===========================================================================
  # FILTERS
  # ===========================================================================
  /filters/systems:
    get:
      operationId: getSystemFilters
      tags:
        - Backend - Filters
      summary: /filters/systems - Get aggregated system filters
      description: |
        Aggregated endpoint that returns all system filter data in a single request.
        Auth is checked once, then products, created_by, versions, and organizations are fetched in parallel.
        Respects RBAC hierarchy - users only see data from systems they can access.

        **Version Format**: Returns versions in prefixed format `product:version` (e.g., `"nsec:1.2.3"`, `"ns8:1.2.3"`)
        to avoid ambiguity when the same version number exists for multiple products.
      responses:
        '200':
          description: System filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system filters retrieved successfully"
                  data:
                    type: object
                    properties:
                      products:
                        type: array
                        items:
                          type: string
                        description: List of unique product names (system types)
                      created_by:
                        type: array
                        items:
                          type: object
                          properties:
                            user_id:
                              type: string
                              description: User logto_id from created_by JSONB field (not UUID)
                              example: "pnqjmgmk937x"
                            name:
                              type: string
                              description: User full name from created_by JSONB field
                              example: "Company Owner"
                            email:
                              type: string
                              description: User email from created_by JSONB field
                              example: "owner@example.com"
                        description: List of users who created systems
                      versions:
                        type: array
                        items:
                          type: object
                          properties:
                            product:
                              type: string
                              description: Product type name
                              example: "NethSecurity"
                            versions:
                              type: array
                              items:
                                type: string
                              description: List of versions in prefixed format (product:version)
                              example: ["nsec:8.6.0", "nsec:8.5.2"]
                        description: Versions grouped by product type
                      organizations:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Organization logto_id (not UUID)
                              example: "ug9v4l0m6mwt"
                            name:
                              type: string
                              description: Organization name
                              example: "Customer Organization 3"
                        description: List of organizations with systems
              example:
                code: 200
                message: "system filters retrieved successfully"
                data:
                  products: ["NethSecurity", "NethServer"]
                  created_by:
                    - user_id: "pnqjmgmk937x"
                      name: "Company Owner"
                      email: "owner@example.com"
                  versions:
                    - product: "nsec"
                      versions: ["nsec:8.6.0", "nsec:8.5.2"]
                    - product: "ns8"
                      versions: ["ns8:1.2.3", "ns8:1.1.0"]
                  organizations:
                    - id: "ug9v4l0m6mwt"
                      name: "Cust3"
                    - id: "guwy6opsll17"
                      name: "Owner"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================================================
  # ROLES & ORGANIZATIONS
  # ===========================================================================
  /organization-roles:
    get:
      operationId: getOrganizationRoles
      tags:
        - Backend - Metadata
      summary: /organization-roles - Get all organization roles
      description: Get all available organization roles with their IDs and descriptions
      responses:
        '200':
          description: Organization roles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "organization roles retrieved successfully"
                  data:
                    type: object
                    properties:
                      organizationRoles:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationRole'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /organizations:
    get:
      operationId: getOrganizations
      tags:
        - Backend - Metadata
      summary: /organizations - Get available organizations
      description: Get organizations the current user can assign users to, filtered by business hierarchy
      responses:
        '200':
          description: Organizations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "organizations retrieved successfully"
                  data:
                    type: object
                    properties:
                      organizations:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationReference'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ===========================================================================
  # BUSINESS HIERARCHY - RESELLERS
  # ===========================================================================
  /resellers:
    get:
      operationId: getResellers
      tags:
        - Backend - Resellers
      summary: /resellers - List resellers
      description: Get paginated list of resellers (Owner + Distributor)
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/ResellerSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/OrganizationStatusFilterParam'
      responses:
        '200':
          description: Resellers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "resellers retrieved successfully"
                  data:
                    type: object
                    properties:
                      resellers:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationWithStats'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      operationId: createReseller
      tags:
        - Backend - Resellers
      summary: /resellers - Create reseller
      description: Create a new reseller organization (Owner + Distributor)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '201':
          description: Reseller created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "reseller created successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /resellers/{id}:
    get:
      operationId: getResellerById
      tags:
        - Backend - Resellers
      summary: /resellers/{id} - Get single reseller
      description: Get a specific reseller by ID (Owner + Distributor)
      parameters:
        - name: id
          in: path
          required: true
          description: Reseller Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Reseller retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller retrieved successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id} - Update reseller
      description: Update a reseller organization (Owner + Distributor)
      parameters:
        - name: id
          in: path
          required: true
          description: Reseller Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '200':
          description: Reseller updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller updated successfully"
                  data:
                    $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

    delete:
      operationId: deleteReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id} - Delete reseller
      description: Delete a reseller organization (Owner + Distributor)
      parameters:
        - name: id
          in: path
          required: true
          description: Reseller Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Reseller deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller deleted successfully"
                  data:
                    type: object
                    properties:
                      deleted_systems_count:
                        type: integer
                        description: Number of systems cascade soft-deleted across the reseller hierarchy
                        example: 3
                      deleted_users_count:
                        type: integer
                        description: Number of users cascade soft-deleted across the reseller hierarchy
                        example: 8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/{id}/stats:
    get:
      operationId: getResellerStats
      tags:
        - Backend - Resellers
      summary: /resellers/{id}/stats - Get reseller statistics
      description: Get users, systems and customers count for a specific reseller (Owner + Distributor + own Reseller)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Reseller Logto ID
      responses:
        '200':
          description: Reseller stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller stats retrieved successfully"
                  data:
                    $ref: '#/components/schemas/ResellerStats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/{id}/suspend:
    patch:
      operationId: suspendReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id}/suspend - Suspend reseller
      description: Suspend a reseller and all its users (cascade suspension). Owner and Distributor (hierarchical) can suspend.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Reseller Logto ID
      responses:
        '200':
          description: Reseller suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller suspended successfully"
                  data:
                    type: object
                    properties:
                      reseller:
                        $ref: '#/components/schemas/Organization'
                      suspended_customers_count:
                        type: integer
                        example: 5
                        description: Number of customers that were cascade-suspended
                      suspended_users_count:
                        type: integer
                        example: 15
                        description: Number of users that were cascade-suspended
                      suspended_systems_count:
                        type: integer
                        example: 10
                        description: Number of systems that were cascade-suspended
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/{id}/reactivate:
    patch:
      operationId: reactivateReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id}/reactivate - Reactivate reseller
      description: Reactivate a suspended reseller and all its cascade-suspended users. Owner and Distributor (hierarchical) can reactivate.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Reseller Logto ID
      responses:
        '200':
          description: Reseller reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller reactivated successfully"
                  data:
                    type: object
                    properties:
                      reseller:
                        $ref: '#/components/schemas/Organization'
                      reactivated_customers_count:
                        type: integer
                        example: 5
                        description: Number of customers that were cascade-reactivated
                      reactivated_users_count:
                        type: integer
                        example: 15
                        description: Number of users that were cascade-reactivated
                      reactivated_systems_count:
                        type: integer
                        example: 10
                        description: Number of systems that were cascade-reactivated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/{id}/restore:
    patch:
      operationId: restoreReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id}/restore - Restore soft-deleted reseller
      description: Restore a soft-deleted reseller (requires manage:resellers permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Reseller Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Reseller restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller restored successfully"
                  data:
                    type: object
                    properties:
                      restored_systems_count:
                        type: integer
                        description: Number of systems cascade restored across the reseller hierarchy
                        example: 3
                      restored_users_count:
                        type: integer
                        description: Number of users cascade restored across the reseller hierarchy
                        example: 8
        '400':
          description: Bad request - Reseller is not deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "reseller is not deleted"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/{id}/destroy:
    delete:
      operationId: destroyReseller
      tags:
        - Backend - Resellers
      summary: /resellers/{id}/destroy - Permanently delete reseller
      description: Permanently delete a reseller organization (requires destroy:resellers permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: Reseller Logto ID
          schema:
            type: string
            example: "jf584cz36kce"
      responses:
        '200':
          description: Reseller permanently destroyed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reseller permanently destroyed"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /resellers/totals:
    get:
      operationId: getResellersTotals
      tags:
        - Backend - Resellers Stats
      summary: /resellers/totals - Get resellers totals
      description: Get total count of resellers accessible to the user (Owner + Distributor)
      responses:
        '200':
          description: Resellers totals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "resellers totals retrieved"
                  data:
                    $ref: '#/components/schemas/Totals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /resellers/trend:
    get:
      operationId: getResellersTrend
      tags:
        - Backend - Resellers Stats
      summary: /resellers/trend - Get resellers trend data
      description: Get trend analysis of resellers over time with cumulative counts (Owner + Distributor)
      parameters:
        - $ref: '#/components/parameters/TrendPeriodParam'
      responses:
        '200':
          description: Resellers trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "resellers trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /resellers/export:
    get:
      operationId: exportResellers
      tags:
        - Backend - Resellers Import/Export
      summary: /resellers/export - Export resellers to CSV or PDF
      description: Export resellers to CSV or PDF format with applied filters (max 10,000 resellers)
      parameters:
        - name: format
          in: query
          required: true
          description: Export format (csv or pdf)
          schema:
            type: string
            enum: [csv, pdf]
            example: "csv"
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/ResellerSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
      responses:
        '200':
          description: Resellers exported successfully
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /roles:
    get:
      operationId: getRoles
      tags:
        - Backend - Metadata
      summary: /roles - Get all user roles
      description: Get all available user roles with their IDs and descriptions
      responses:
        '200':
          description: Roles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "roles retrieved successfully"
                  data:
                    type: object
                    properties:
                      roles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ===========================================================================
  # SYSTEMS MANAGEMENT
  # ===========================================================================
  /systems:
    get:
      operationId: getSystems
      tags:
        - Backend - Systems
      summary: /systems - List systems
      description: |
        Get list of systems visible to the user based on hierarchical organization permissions. Supports filtering by name, type, creator, version, organization, and status.

        **Query String Examples:**

        1. **Single type filter**: `?type=nsec`
        2. **Multiple types filter**: `?type=nsec&type=ns8`
        3. **Multiple filters combined**: `?type=nsec&status=active&status=deleted&version=8.0`
        4. **With pagination and sorting**: `?page=1&page_size=50&sort_by=name&sort_direction=asc&type=nsec`
        5. **Search with filters**: `?search=backup&type=ns8&organization_id=org_abc123xyz`
        6. **Creator filter (by user)**: `?created_by=53h5zxpwu4vc`
        7. **Creator filter (by organization)**: `?created_by=lbswt1rxdhbz`
        8. **Creator filter (multiple)**: `?created_by=53h5zxpwu4vc&created_by=lbswt1rxdhbz`

        **Complete Example Request:**
        ```
        GET /api/systems?page=1&page_size=20&sort_by=created_at&sort_direction=desc&type=nsec&type=ns8&status=active&version=nsec:8.0&version=ns8:1.2.3&organization_id=org_abc123xyz
        ```

        This retrieves systems that are:
        - Type: nsec OR ns8
        - Status: active
        - Version: (nsec version 8.0) OR (ns8 version 1.2.3)
        - Organization: org_abc123xyz
        - Sorted by creation date (newest first)
        - Page 1 with 20 items per page
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/SystemSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/SystemNameFilterParam'
        - $ref: '#/components/parameters/SystemKeyFilterParam'
        - $ref: '#/components/parameters/SystemTypeFilterParam'
        - $ref: '#/components/parameters/SystemCreatedByFilterParam'
        - $ref: '#/components/parameters/SystemVersionFilterParam'
        - $ref: '#/components/parameters/SystemOrganizationFilterParam'
        - $ref: '#/components/parameters/SystemStatusFilterParam'
      responses:
        '200':
          description: Systems retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "systems retrieved successfully"
                  data:
                    type: object
                    properties:
                      systems:
                        type: array
                        items:
                          $ref: '#/components/schemas/System'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      operationId: createSystem
      tags:
        - Backend - Systems
      summary: /systems - Create system
      description: Create a new system. Users can create systems for organizations they can manage based on hierarchical permissions. The organization_id must be specified in the request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSystemInput'
      responses:
        '201':
          description: System created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "system created successfully"
                  data:
                    $ref: '#/components/schemas/System'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/{id}:
    get:
      operationId: getSystemById
      tags:
        - Backend - Systems
      summary: /systems/{id} - Get single system
      description: Get a specific system by ID. Users can access systems created by their organization based on hierarchical permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system retrieved successfully"
                  data:
                    $ref: '#/components/schemas/System'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateSystem
      tags:
        - Backend - Systems
      summary: /systems/{id} - Update system
      description: Update a system. All fields are optional. Users can update systems created by their organization based on hierarchical permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSystemInput'
      responses:
        '200':
          description: System updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system updated successfully"
                  data:
                    $ref: '#/components/schemas/System'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteSystem
      tags:
        - Backend - Systems
      summary: /systems/{id} - Delete system
      description: Delete a system. Users can delete systems created by their organization based on hierarchical permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system deleted successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/restore:
    patch:
      operationId: restoreSystem
      tags:
        - Backend - Systems
      summary: /systems/{id}/restore - Restore soft-deleted system
      description: Restore a soft-deleted system. Users can restore systems they have permission to delete based on hierarchical permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System restored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system restored successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          description: Bad request - System is not deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "system is not deleted"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/destroy:
    delete:
      operationId: destroySystem
      tags:
        - Backend - Systems
      summary: /systems/{id}/destroy - Permanently delete system
      description: Permanently delete a system (requires destroy:systems permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System permanently destroyed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system permanently destroyed"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/suspend:
    patch:
      operationId: suspendSystem
      tags:
        - Backend - Systems
      summary: /systems/{id}/suspend - Suspend system
      description: Suspend a system (requires manage:systems permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system suspended successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/reactivate:
    patch:
      operationId: reactivateSystem
      tags:
        - Backend - Systems
      summary: /systems/{id}/reactivate - Reactivate suspended system
      description: Reactivate a suspended system (requires manage:systems permission and hierarchical validation)
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System reactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system reactivated successfully"
                  data:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/regenerate-secret:
    post:
      operationId: regenerateSystemSecret
      tags:
        - Backend - Systems
      summary: /systems/{id}/regenerate-secret - Regenerate system secret
      description: Regenerate authentication secret for a specific system. Users can regenerate secrets for systems created by their organization based on hierarchical permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: System secret regenerated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system secret regenerated successfully"
                  data:
                    $ref: '#/components/schemas/System'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/reachability:
    get:
      operationId: checkSystemReachability
      tags:
        - Backend - Systems
      summary: /systems/{id}/reachability - Check if system web UI is reachable
      description: |
        Checks if the system's web UI is reachable from the backend server.
        The target URL is constructed from the system's FQDN and type:
        - NS8: `https://{fqdn}/cluster-admin`
        - NethSecurity: tries `https://{fqdn}:443` first, then `https://{fqdn}:9090`

        Returns `reachable: true` with the responding `url` on success, or `reachable: false` if unreachable.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Reachability check completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "reachability check completed"
                  data:
                    type: object
                    properties:
                      reachable:
                        type: boolean
                        example: true
                      url:
                        type: string
                        description: The URL that responded successfully (empty if not reachable)
                        example: "https://firewall.example.com:9090"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/register:
    post:
      operationId: registerSystem
      tags:
        - Backend - Systems
      security: []
      summary: /systems/register - Register system with system_secret
      description: |
        Public endpoint for external systems to register themselves using their system_secret token.
        This endpoint does NOT require authentication - the system_secret itself provides authentication.

        **Token Format:** `my_<public_part>.<secret_part>`

        **Workflow:**
        1. User creates system in management UI → receives system_secret (one time only)
        2. External system uses system_secret to register → receives system_key
        3. External system uses system_key for future operations (inventory, heartbeat)

        **Important:**
        - Systems can only be registered once
        - Deleted systems cannot be registered
        - The system_secret is validated using SHA256 hashing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - system_secret
              properties:
                system_secret:
                  type: string
                  description: System secret token in format my_<public>.<secret>
                  example: "my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0"
      responses:
        '200':
          description: System registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system registered successfully"
                  data:
                    type: object
                    properties:
                      system_key:
                        type: string
                        description: System key to use for future operations
                        example: "my_sys_a1b2c3d4e5f6g7h8"
                      registered_at:
                        type: string
                        format: date-time
                        description: Timestamp when system was registered
                        example: "2025-11-06T10:30:00Z"
        '400':
          description: Invalid system secret format
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "invalid system secret format"
        '401':
          description: Invalid system secret (authentication failed)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: "invalid system secret"
        '403':
          description: System has been deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: "system has been deleted"
        '409':
          description: System is already registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 409
                  message:
                    type: string
                    example: "system is already registered"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /systems/totals:
    get:
      operationId: getSystemsTotals
      tags:
        - Backend - Systems Stats
      summary: /systems/totals - Get systems status summary
      description: Get systems heartbeat status summary for dashboard (requires Admin or Support role)
      parameters:
        - name: timeout
          in: query
          description: Timeout in minutes for active/inactive determination
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 15
            example: 15
      responses:
        '200':
          description: Systems status summary retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system status retrieved"
                  data:
                    $ref: '#/components/schemas/SystemTotals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/trend:
    get:
      operationId: getSystemsTrend
      tags:
        - Backend - Systems Stats
      summary: /systems/trend - Get systems trend data
      description: Get trend analysis of systems over time with cumulative counts
      parameters:
        - $ref: '#/components/parameters/TrendPeriodParam'
      responses:
        '200':
          description: Systems trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "systems trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/export:
    get:
      operationId: exportSystems
      tags:
        - Backend - Systems Stats
      summary: /systems/export - Export systems to CSV or PDF
      description: |
        Export systems with applied filters to CSV or PDF format.

        **Features:**
        - Supports all filter parameters from GET /systems
        - Maximum 10,000 systems per export (DoS protection)
        - CSV format: Simple spreadsheet with all fields
        - PDF format: Formatted report with metadata and filters applied
        - File naming: `systems_export_YYYY-MM-DD_HHmmss.[csv|pdf]`

        **Permissions**: Requires `read:systems` permission and respects RBAC hierarchy

        **Export Fields:**
        - Name, Type, Version, Status
        - FQDN, IPv4 Address, IPv6 Address
        - System Key, Notes
        - Created At
        - Organization Name, Organization Type
        - Created By Name, Created By Email, Created By Organization
      parameters:
        - name: format
          in: query
          required: true
          description: Export format (csv or pdf)
          schema:
            type: string
            enum: [csv, pdf]
            example: csv
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/SystemSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/SystemNameFilterParam'
        - $ref: '#/components/parameters/SystemKeyFilterParam'
        - $ref: '#/components/parameters/SystemTypeFilterParam'
        - $ref: '#/components/parameters/SystemCreatedByFilterParam'
        - $ref: '#/components/parameters/SystemVersionFilterParam'
        - $ref: '#/components/parameters/SystemOrganizationFilterParam'
        - $ref: '#/components/parameters/SystemStatusFilterParam'
      responses:
        '200':
          description: Export file generated successfully
          content:
            text/csv:
              schema:
                type: string
                format: binary
                description: CSV file with systems data
            application/pdf:
              schema:
                type: string
                format: binary
                description: PDF report with systems data
          headers:
            Content-Disposition:
              description: Attachment filename
              schema:
                type: string
                example: 'attachment; filename="systems_export_2025-01-26_153045.csv"'
            Content-Length:
              description: File size in bytes
              schema:
                type: integer
        '400':
          description: Bad request (invalid format or too many systems)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: "too many systems to export (15000). maximum allowed: 10000. please apply more filters"
                  data:
                    type: object
                    properties:
                      total_count:
                        type: integer
                        example: 15000
                      max_limit:
                        type: integer
                        example: 10000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/{id}/inventory:
    get:
      operationId: getSystemInventory
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory - Get system inventory history
      description: Get paginated inventory history for a specific system. Supports date range filtering.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: from_date
          in: query
          required: false
          description: Filter records from this date (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-01-01T00:00:00Z"
        - name: to_date
          in: query
          required: false
          description: Filter records up to this date (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-02-20T23:59:59Z"
      responses:
        '200':
          description: Inventory history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "inventory history retrieved successfully"
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/InventoryRecord'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/inventory/latest:
    get:
      operationId: getSystemInventoryLatest
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/latest - Get latest system inventory
      description: Get the most recent inventory data for a specific system. Returns the full InventoryRecord including the raw inventory JSON in the `data` field.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Latest inventory retrieved successfully. Returns null when no inventory is available (not an error condition).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "latest inventory retrieved successfully"
                  data:
                    type: object
                    nullable: true
                    description: Latest inventory record, or null if no inventory exists
                    allOf:
                      - $ref: '#/components/schemas/InventoryRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/{id}/inventory/{inventory_id}:
    get:
      operationId: getSystemInventoryByID
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/{inventory_id} - Get a specific inventory record
      description: Get a specific inventory record by its ID, scoped to the system.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - name: inventory_id
          in: path
          required: true
          description: Inventory record ID
          schema:
            type: integer
            format: int64
            example: 42
      responses:
        '200':
          description: Inventory record retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "inventory record retrieved successfully"
                  data:
                    $ref: '#/components/schemas/InventoryRecord'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/inventory/changes:
    get:
      operationId: getSystemInventoryChanges
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/changes - Get inventory changes summary
      description: Get an aggregated summary of all inventory changes for a specific system. Returns counts grouped by category and severity, not a paginated list.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Changes summary retrieved successfully. Returns null when no inventory is available (not an error condition).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "changes summary retrieved successfully"
                  data:
                    type: object
                    nullable: true
                    description: Aggregated changes summary, or null if no inventory exists
                    allOf:
                      - $ref: '#/components/schemas/InventoryChangesSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/{id}/inventory/changes/latest:
    get:
      operationId: getSystemInventoryChangesLatest
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/changes/latest - Get latest inventory changes
      description: Get the changes summary scoped to the most recent inventory batch only. The `recent_changes` field equals `total_changes` since all changes are from the latest batch.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Latest inventory changes summary retrieved successfully. Returns null when no inventory is available (not an error condition).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "latest inventory changes summary retrieved successfully"
                  data:
                    type: object
                    nullable: true
                    description: Changes summary for the latest inventory batch, or null if no inventory exists
                    allOf:
                      - $ref: '#/components/schemas/InventoryChangesSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /systems/{id}/inventory/diffs:
    get:
      operationId: getSystemInventoryDiffs
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/diffs - Get inventory diffs
      description: Get paginated inventory diffs for a specific system. Supports filtering by severity, category, diff type, date range, and text search on field path and values.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: search
          in: query
          required: false
          description: "Case-insensitive text search across field_path, previous_value, and current_value."
          schema:
            type: string
            minLength: 1
            example: "network"
        - name: severity
          in: query
          required: false
          description: Filter by severity level. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [low, medium, high, critical]
            example: ["high", "critical"]
          style: form
          explode: true
        - name: category
          in: query
          required: false
          description: Filter by change category. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [os, hardware, network, security, backup, features, modules, cluster, nodes, system]
            example: ["os", "network"]
          style: form
          explode: true
        - name: diff_type
          in: query
          required: false
          description: Filter by diff type. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [create, update, delete]
            example: ["create", "update"]
          style: form
          explode: true
        - name: inventory_id
          in: query
          required: false
          description: Filter by specific inventory record IDs. Supports multiple values. Use the `inventory_ids` from a `/timeline` group to fetch diffs for that date group.
          schema:
            type: array
            items:
              type: integer
              format: int64
            example: [42, 43]
          style: form
          explode: true
        - name: from_date
          in: query
          required: false
          description: Filter diffs from this date (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-01-01T00:00:00Z"
        - name: to_date
          in: query
          required: false
          description: Filter diffs up to this date (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-02-20T23:59:59Z"
      responses:
        '200':
          description: Inventory diffs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "inventory diffs retrieved successfully"
                  data:
                    type: object
                    properties:
                      diffs:
                        type: array
                        items:
                          $ref: '#/components/schemas/InventoryDiff'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/inventory/diffs/latest:
    get:
      operationId: getSystemInventoryDiffsLatest
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/diffs/latest - Get latest inventory diffs batch
      description: Get all diffs from the most recent inventory snapshot. Returns the complete batch (not paginated), ordered by severity (critical first) then by creation time descending.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Latest inventory diffs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "latest inventory diffs retrieved successfully"
                  data:
                    type: object
                    description: Latest diffs batch data
                    properties:
                      diffs:
                        type: array
                        items:
                          $ref: '#/components/schemas/InventoryDiff'
                      count:
                        type: integer
                        description: Number of diffs in this batch
                        example: 5
                      current_inventory_id:
                        type: integer
                        format: int64
                        description: ID of the current inventory record these diffs belong to. Only present when there are diffs.
                        example: 42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/inventory/timeline:
    get:
      operationId: getSystemInventoryTimeline
      tags:
        - Backend - Systems Inventory
      summary: /systems/{id}/inventory/timeline - Get inventory timeline grouped by date
      description: |
        Get a date-grouped inventory timeline for a specific system.
        Returns a filtered summary (severity counters) and groups of inventory dates.
        Each group includes `inventory_ids` — the IDs of inventory records collected that day.
        Groups with no matching diffs still appear with `change_count: 0`, allowing the UI
        to display "X inventories, no changes" badges. Pagination is over date groups.
        To fetch the actual diffs for a group, call `GET /systems/{id}/inventory/diffs?inventory_id=42&inventory_id=43`
        with the `inventory_ids` from the group.
        Supports text search on diff field paths and values.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: search
          in: query
          required: false
          description: "Case-insensitive text search across diff field_path, previous_value, and current_value. Affects change_count in groups and summary counters."
          schema:
            type: string
            minLength: 1
            example: "dhcp"
        - name: severity
          in: query
          required: false
          description: Filter by severity level. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [low, medium, high, critical]
            example: ["high", "critical"]
          style: form
          explode: true
        - name: category
          in: query
          required: false
          description: Filter by change category. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [os, hardware, network, security, backup, features, modules, cluster, nodes, system]
            example: ["os", "security"]
          style: form
          explode: true
        - name: diff_type
          in: query
          required: false
          description: Filter by diff type. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [create, update, delete]
            example: ["create", "update"]
          style: form
          explode: true
        - name: from_date
          in: query
          required: false
          description: Show dates from this timestamp (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-01-01T00:00:00Z"
        - name: to_date
          in: query
          required: false
          description: Show dates up to this timestamp (RFC3339 format)
          schema:
            type: string
            format: date-time
            example: "2026-03-17T23:59:59Z"
      responses:
        '200':
          description: Inventory timeline retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "inventory timeline retrieved successfully"
                  data:
                    type: object
                    properties:
                      summary:
                        $ref: '#/components/schemas/InventoryTimelineSummary'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/InventoryTimelineGroup'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /alerts:
    get:
      operationId: getAlerts
      tags:
        - Backend - Alerts
      summary: "/alerts - List active alerts (cross-hierarchy)"
      description: |
        Retrieves active alerts from Mimir for the caller's scope, paginated. Each
        alert is enriched with a `system` object (`name`, `type`) looked up from the
        local `systems` table, so the UI can render the system column without an
        extra round-trip per row.

        Sortable by `starts_at` (default desc), `severity` (criticality rank: critical
        > warning > info), `alertname`, or `status` (Alertmanager state). `fingerprint`
        is used as a stable tiebreaker so pagination doesn't shift between requests.

        Scope follows the same three modes as `/alerts/totals`:
        - `organization_id` omitted → caller's full hierarchy (cross-tenant fan-out).
        - `organization_id=X` → single tenant `X`.
        - `organization_id=X&include=descendants` → `X` plus its sub-tree.

        All filter params support **multiple values** (repeat the param): values within
        the same filter are matched as OR; different filters AND together. Example:
        `?severity=critical&severity=warning&alertname=CVE-2024-1234` returns
        CVE-2024-1234 alerts that are critical or warning.

        Per-tenant failures during fan-out (timeout, 5xx) are non-fatal: the rest of the
        result is returned and the failure is reported in the `warnings` array.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param to pass multiple values.
            Optional for all roles except Customer (where it is ignored).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          description: Set to `descendants` together with `organization_id` to expand each value to its sub-tree.
          schema:
            type: string
            enum: [descendants]
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Page size. Default 50, max 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: sort_by
          in: query
          description: Sort column (allowlist).
          schema:
            type: string
            enum: [starts_at, severity, alertname, status]
            default: starts_at
        - name: sort_direction
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: status
          in: query
          description: Filter alerts by Alertmanager state. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [active, suppressed, unprocessed]
          style: form
          explode: true
        - name: severity
          in: query
          description: Filter alerts by severity label. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [critical, warning, info]
          style: form
          explode: true
        - name: system_key
          in: query
          description: Filter alerts by system_key label. Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: alertname
          in: query
          description: |
            Filter alerts by alertname label (the alert "type" — e.g. `HighCPU`,
            `DiskFull`, `CVE-2024-1234`). Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Paginated list of active alerts
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alerts retrieved successfully
                  data:
                    type: object
                    properties:
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/ActiveAlert'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      warnings:
                        type: array
                        description: |
                          Per-tenant errors encountered during fan-out. Always present
                          (empty array when every tenant responded OK). Each entry is
                          a string `org <logto_id>: <error>`.
                        items:
                          type: string
              examples:
                ActiveAlertExample:
                  summary: One active warning across the caller's hierarchy
                  description: |
                    A single warning alert. System identity (id, key, name, type) is
                    carried as labels, stamped at ingest time. `state="active"` means
                    Mimir has not been told to silence it; an actively-muted alert
                    would have `state="suppressed"` and a non-empty `silencedBy`.
                  value:
                    code: 200
                    message: alerts retrieved successfully
                    data:
                      alerts:
                        - fingerprint: "0a9d04bb6eed523f"
                          labels:
                            alertname: "DiskFilling"
                            severity: "warning"
                            system_id: "e4eb4844-46f6-448c-8279-7cfedf5e1037"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                            system_name: "test-sys"
                            system_type: "ns8"
                          annotations:
                            summary: "/var is 92% full on test-sys"
                            description: "Disk usage exceeded the warning threshold."
                          status:
                            state: "active"
                            silencedBy: []
                            inhibitedBy: []
                          startsAt: "2026-05-12T08:14:00Z"
                          endsAt: "2026-05-12T08:44:00Z"
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 1
                        total_pages: 1
                        has_next: false
                        has_prev: false
                      warnings: []
                PartialFanoutWarning:
                  summary: One tenant timed out during fan-out
                  description: |
                    When `organization_id` is omitted (or `include=descendants` is
                    used), the request fans out to every tenant in scope. A single
                    slow Mimir does not fail the whole request — the rest of the
                    results are returned and the failing tenant lands in `warnings`.
                  value:
                    code: 200
                    message: alerts retrieved successfully
                    data:
                      alerts: []
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 0
                        total_pages: 0
                        has_next: false
                        has_prev: false
                      warnings:
                        - "org pt8gqs6y5wpr: context deadline exceeded"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ===========================================
  # ALERTING ENDPOINTS (Collect - Mimir Proxy)
  # ===========================================

  /alerts/totals:
    get:
      operationId: getAlertsTotals
      tags:
        - Backend - Alerts
      summary: "/alerts/totals - Get alert totals by severity"
      description: |
        Returns active alert counts by severity (from Mimir, per-tenant) and total resolved
        alert history count (from DB). Requires `read:systems` permission.

        **Scope modes** (selected by query params):

        | `organization_id`            | `include`     | Result |
        |---|---|---|
        | omitted                      | —             | Caller's full hierarchy (recursive). For Customer it's just self. |
        | `X`                          | omitted       | Single tenant `X` only. Resellers/Distributors hold no alerts on their own tenant — those live on their customer tenants — so single-tenant queries on a non-leaf org typically return zero. |
        | `X` (repeated for multi)     | omitted       | Union of all `organization_id` values passed. Each must be in the caller's hierarchy (Owner exempt). |
        | `X` (single or multi)        | `descendants` | Each org_id is expanded to itself + its sub-tree (deduplicated). Use this to drill into one or more sub-trees. |

        Active counts are aggregated across the resolved scope by fanning out to Mimir,
        one request per tenant, with bounded concurrency and a global timeout. Per-tenant
        failures (timeout, 5xx, parse error) are non-fatal: their counts simply don't
        contribute, and the failure is reported in the `warnings` array. The `history`
        total comes from a single SQL query scoped to the same set of organization IDs.

        Customer callers are always pinned to their own organization regardless of
        `organization_id`/`include` (Mimir tenant is fixed to `user.organization_id`).
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param to pass multiple values
            (`?organization_id=A&organization_id=B`). Optional for all roles except
            Customer (where it is ignored). Distributors/Resellers receive `403` if any
            value is not in their hierarchy.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          description: |
            Set to `descendants` together with `organization_id` to expand each value
            to its full sub-tree (results deduplicated). Ignored when `organization_id`
            is omitted (the caller's own hierarchy is already used) and when the caller
            is a Customer.
          schema:
            type: string
            enum: [descendants]
      responses:
        '200':
          description: Alert totals retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alert totals retrieved successfully
                  data:
                    type: object
                    properties:
                      active:
                        type: integer
                        description: Total active alerts in scope
                      critical:
                        type: integer
                        description: Active critical alerts in scope
                      warning:
                        type: integer
                        description: Active warning alerts in scope
                      info:
                        type: integer
                        description: Active info alerts in scope
                      muted:
                        type: integer
                        description: Active alerts currently silenced (Alertmanager `silencedBy` non-empty)
                      history:
                        type: integer
                        description: Total resolved alerts in history (DB) in scope
                      warnings:
                        type: array
                        description: |
                          Per-tenant errors encountered during fan-out. Always present
                          (empty array when every tenant responded OK). Each entry is a
                          string in the form `org <logto_id>: <error>` or
                          `history: <error>` for the DB lookup.
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /alerts/trend:
    get:
      operationId: getAlertsTrend
      tags:
        - Backend - Alerts
      summary: "/alerts/trend - Get alert history trend"
      description: |
        Returns trend data for resolved alerts over a specified period with daily data points.
        Compares the current period with the previous period of equal length.
        Requires `read:systems` permission.

        Scope follows the same three modes as `/alerts/totals`:
        - `organization_id` omitted → caller's full hierarchy.
        - `organization_id=X` → single tenant `X`.
        - `organization_id=X&include=descendants` → `X` plus its sub-tree.

        Customer callers are always pinned to their own organization regardless of params.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param to pass multiple values.
            Optional for all roles except Customer (where it is ignored).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          description: Set to `descendants` together with `organization_id` to expand each value to its sub-tree.
          schema:
            type: string
            enum: [descendants]
        - name: period
          in: query
          description: Trend period in days
          schema:
            type: integer
            enum: [7, 30, 180, 365]
            default: 7
      responses:
        '200':
          description: Alert trend data
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alerts trend retrieved successfully
                  data:
                    type: object
                    properties:
                      period:
                        type: integer
                      period_label:
                        type: string
                      current_total:
                        type: integer
                      previous_total:
                        type: integer
                      delta:
                        type: integer
                      delta_percentage:
                        type: number
                      trend:
                        type: string
                        enum: [up, down, stable]
                      data_points:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            count:
                              type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /alerts/stats:
    get:
      operationId: getAlertsStats
      tags:
        - Backend - Alerts
      summary: "/alerts/stats - Aggregate alert statistics"
      description: |
        Returns aggregate statistics over `alert_history` for the caller's scope:
        total, severity buckets, top-N alertname and system_key by count, plus MTTR
        (mean time to resolve) and MTBF (mean time between failures, approximated).

        Scope follows the same three modes as `/alerts/totals`:
        - `organization_id` omitted → caller's full hierarchy.
        - `organization_id=X` → single tenant.
        - `organization_id=X&include=descendants` → sub-tree drill-down.

        MTBF formula:
        - When both `from_date` and `to_date` are provided: `(to - from) / total`.
        - Otherwise: `(max(starts_at) - min(starts_at)) / (total - 1)`.
        - Omitted from the response when the result is undefined.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param to pass multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          schema:
            type: string
            enum: [descendants]
        - name: from_date
          in: query
          description: Lower bound on `created_at` (inclusive). RFC3339 timestamp.
          schema:
            type: string
            format: date-time
            example: "2026-05-01T00:00:00Z"
        - name: to_date
          in: query
          description: Upper bound on `created_at` (exclusive). RFC3339 timestamp.
          schema:
            type: string
            format: date-time
            example: "2026-05-08T00:00:00Z"
        - name: top
          in: query
          description: Cap for top-N alertname / system_key buckets. Default 10, max 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Alert stats retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alert stats retrieved successfully
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total alerts in scope (sum of severity buckets, including null severity).
                      by_severity:
                        type: object
                        additionalProperties:
                          type: integer
                        example:
                          critical: 30
                          warning: 100
                          info: 26
                      top_alertnames:
                        type: array
                        items:
                          type: object
                          properties:
                            alertname:
                              type: string
                            count:
                              type: integer
                      top_systems:
                        type: array
                        items:
                          type: object
                          properties:
                            system_key:
                              type: string
                            count:
                              type: integer
                      mttr_seconds:
                        type: integer
                        description: Mean time to resolve (avg `ends_at - starts_at` over rows with `ends_at` set). Omitted when no resolved alerts.
                      mtbf_seconds:
                        type: integer
                        description: Mean time between failures (approximation, see endpoint description). Omitted when undefined.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /alerts/history:
    get:
      operationId: getAlertsHistory
      tags:
        - Backend - Alerts
      summary: "/alerts/history - Org-level paginated alert history"
      description: |
        Returns paginated resolved alert history scoped to the caller's hierarchy
        (no `organization_id`), a single tenant (`organization_id=X`), or a sub-tree
        (`organization_id=X&include=descendants`). Mirrors the scope rules of
        `/alerts/totals` and `/alerts/trend`.

        Supports date range (`from_date`/`to_date`, RFC3339) and multi-value label
        filters (`system_key`, `alertname`, `severity`, `status`). All multi-value
        filters: OR within the same filter, AND across filters.

        Customer callers are always pinned to their own organization regardless of params.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param to pass multiple values.
            Optional for all roles except Customer (where it is ignored).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          description: Set to `descendants` together with `organization_id` to expand each value to its sub-tree.
          schema:
            type: string
            enum: [descendants]
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [id, alertname, severity, status, starts_at, ends_at, created_at]
            default: created_at
        - name: sort_direction
          in: query
          required: false
          description: |
            Sort direction. Unlike the shared default of `asc`, this endpoint
            defaults to `desc` so the natural "most recent first" ordering is
            applied when the caller omits the param.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: from_date
          in: query
          description: Lower bound on `created_at` (inclusive). RFC3339 timestamp.
          schema:
            type: string
            format: date-time
            example: "2026-05-01T00:00:00Z"
        - name: to_date
          in: query
          description: Upper bound on `created_at` (exclusive). RFC3339 timestamp. Must be after `from_date`.
          schema:
            type: string
            format: date-time
            example: "2026-05-08T00:00:00Z"
        - name: system_key
          in: query
          description: |
            Filter by one or more system keys. Repeat the param to pass multiple
            values; results are matched as `system_key IN (...)`.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: alertname
          in: query
          description: Filter by alertname. Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: severity
          in: query
          description: Filter by severity. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [critical, warning, info]
          style: form
          explode: true
        - name: status
          in: query
          description: Filter by status. Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Paginated alert history
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alert history retrieved successfully
                  data:
                    type: object
                    properties:
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/AlertHistoryRecord'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
              examples:
                TwoResolvedAlerts:
                  summary: Two resolved alerts on the same system
                  description: |
                    Result for a Customer caller. Same `system_key` appears in both
                    rows because they were fired against the same NS8 host. Each
                    row is a discrete event (firing → resolved) captured by the
                    history webhook at dispatch time; `created_at` records when
                    the row landed in `alert_history`.
                  value:
                    code: 200
                    message: alert history retrieved successfully
                    data:
                      alerts:
                        - id: 55
                          organization_id: "m4m3mdjdiizs"
                          system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          alertname: "PlainBodyTest"
                          severity: "critical"
                          status: "resolved"
                          fingerprint: "11a9302b0fa6526e"
                          starts_at: "2026-05-12T07:46:50Z"
                          ends_at: "2026-05-12T07:51:50Z"
                          summary: "plain body check"
                          labels:
                            alertname: "PlainBodyTest"
                            severity: "critical"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          annotations:
                            summary: "plain body check"
                            description: "checking html:'' fix"
                          receiver: "severity-critical-receiver"
                          created_at: "2026-05-12T07:52:00Z"
                        - id: 54
                          organization_id: "m4m3mdjdiizs"
                          system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          alertname: "HistFlowTest"
                          severity: "critical"
                          status: "resolved"
                          fingerprint: "9c1a23e87f4d0a11"
                          starts_at: "2026-05-12T08:01:07Z"
                          ends_at: "2026-05-12T08:06:06Z"
                          summary: "history flow check"
                          labels:
                            alertname: "HistFlowTest"
                            severity: "critical"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          annotations:
                            summary: "history flow check"
                            description: "resolved"
                          receiver: "severity-critical-receiver"
                          created_at: "2026-05-12T08:11:30Z"
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 2
                        total_pages: 1
                        has_next: false
                        has_prev: false
                EmptyHistory:
                  summary: No history rows match
                  value:
                    code: 200
                    message: alert history retrieved successfully
                    data:
                      alerts: []
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 0
                        total_pages: 0
                        has_next: false
                        has_prev: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================
  # ALERTING ENDPOINTS (Per-alert audit timeline)
  # ===========================================

  /alerts/activity/{fingerprint}:
    parameters:
      - name: fingerprint
        in: path
        required: true
        description: |
          Alertmanager fingerprint of the alert (hex hash of its labels).
          Stable across re-firings of the same alert.
        schema:
          type: string
          pattern: '^[A-Za-z0-9._:-]{1,128}$'
      - name: organization_id
        in: query
        required: true
        description: Tenant the alert belongs to. Required for non-Customer roles.
        schema:
          type: string
    get:
      operationId: getAlertActivity
      tags:
        - Backend - Alerts
      summary: "/alerts/activity/{fingerprint} - Per-alert audit timeline"
      description: |
        Returns the audit timeline for the alert identified by `fingerprint`, most recent
        first. Events are written transparently as silences are created, updated, or
        removed via the `/api/alerts/silences` and `/api/systems/:id/alerts/silences` endpoints.

        Operator notes are stored as the silence `comment` (Alertmanager native), so a
        note edit appears here as a `silence_updated` event whose `details` payload
        includes the new comment.

        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Max events to return. Default 100, max 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Activity timeline
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alert activity retrieved successfully
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          $ref: '#/components/schemas/AlertActivityEntry'
              examples:
                SilenceCreatedThenRemoved:
                  summary: A silence was created and later removed
                  description: |
                    Events are most-recent first. Both rows share the same
                    `silence_id` because they describe the same silence's
                    lifecycle. `actor_user_id` is the logto_id of the operator
                    who performed the action; `details` carries the silence
                    metadata captured at action time (comment, end_at, etc.).
                  value:
                    code: 200
                    message: alert activity retrieved successfully
                    data:
                      events:
                        - id: 5
                          organization_id: "m4m3mdjdiizs"
                          fingerprint: "0a9d04bb6eed523f"
                          action: "unsilenced"
                          actor_user_id: "c5gpnoo2do48"
                          actor_name: "R1C1 Admin"
                          silence_id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                          details: {}
                          created_at: "2026-05-12T08:20:38.410596Z"
                        - id: 4
                          organization_id: "m4m3mdjdiizs"
                          fingerprint: "0a9d04bb6eed523f"
                          action: "silenced"
                          actor_user_id: "c5gpnoo2do48"
                          actor_name: "R1C1 Admin"
                          silence_id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                          details:
                            comment: "silenced during maintenance window"
                            end_at: "2026-05-12T09:16:36Z"
                            duration_minutes: 0
                          created_at: "2026-05-12T08:16:36.661832Z"
                EmptyTimeline:
                  summary: No silence events yet
                  description: |
                    The alert has fired but has never been silenced. The events
                    array is empty (not `null`).
                  value:
                    code: 200
                    message: alert activity retrieved successfully
                    data:
                      events: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ===========================================
  # ALERTING ENDPOINTS (Backend - Cross-system silences)
  # ===========================================

  /alerts/config:
    post:
      operationId: configureAlerts
      tags:
        - Backend - Alerts Configuration
      summary: "/alerts/config - Save the caller's alerting layer"
      description: |
        Saves the CALLER's alerting configuration layer (one row per
        organization in alert_config_layers). The body is an
        `AlertingConfigLayer`: three channel toggles plus three recipient
        lists. Each recipient carries its own `severities[]`; email
        recipients additionally carry `language` and `format`.

        After save, the effective per-tenant Mimir YAML is recomputed
        server-side (merge of all layers walking up to the Owner) and
        pushed to every tenant in the caller's hierarchy with bounded
        concurrency. Per-tenant push failures are returned in `warnings[]`;
        the caller's layer is saved regardless of push outcome (Mimir can
        be reconciled by saving again).

        Additive-only contract: descendants can ADD recipients but cannot
        disable channels enabled by ancestors. The server normalises any
        explicit `false` in `enabled.{email,webhook,telegram}` from
        non-Owner layers to null on storage.

        Save+propagate is serialised per-organization (in-process mutex) to
        prevent two concurrent saves from racing at the Mimir push step.
        Body is capped at 1 MiB; oversized payloads are rejected with 413.

        Requires `manage:alerts` permission.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertingConfigLayer'
            examples:
              OwnerGlobalBaseline:
                summary: Owner — global baseline
                description: |
                  Owner enables email + webhook globally, sets a NOC
                  recipient on all severities in Italian HTML, plus a SIEM
                  webhook on every severity. Every descendant inherits.
                value:
                  enabled: { email: true, webhook: true, telegram: false }
                  email_recipients:
                    - address: "noc@msp.example"
                      severities: []
                      language: "it"
                      format: "html"
                  webhook_recipients:
                    - name: "central-siem"
                      url: "https://siem.example/api/alerts"
                      severities: []
                  telegram_recipients: []
              DescendantAddRecipient:
                summary: Reseller — additively add a recipient
                description: |
                  Reseller does NOT touch channel toggles (null = "no
                  opinion"); it just adds a local NOC mailbox in English
                  for critical+warning. Merged with Owner's recipients.
                value:
                  enabled: { email: null, webhook: null, telegram: null }
                  email_recipients:
                    - address: "noc@reseller.example"
                      severities: ["critical", "warning"]
                      language: "en"
                      format: "html"
                  webhook_recipients: []
                  telegram_recipients: []
              CustomerMixedFormatAndLang:
                summary: Customer — mixed languages and formats per recipient
                description: |
                  Different recipients can request different bodies. The
                  on-call inbox wants plain text (alerts piped into a
                  ticketing tool); the manager wants HTML in Italian.
                value:
                  enabled: { email: null, webhook: null, telegram: null }
                  email_recipients:
                    - address: "oncall@customer.example"
                      severities: ["critical"]
                      language: "en"
                      format: "plain"
                    - address: "manager@customer.example"
                      severities: []
                      language: "it"
                      format: "html"
                  webhook_recipients: []
                  telegram_recipients: []
              CustomerWebhookCriticalOnly:
                summary: Customer — Slack webhook only for `critical`
                description: |
                  Customer adds a Slack webhook scoped to critical. The
                  rendered Alertmanager route puts this webhook only on
                  the critical receiver.
                value:
                  enabled: { email: null, webhook: null, telegram: null }
                  email_recipients: []
                  webhook_recipients:
                    - name: "ops-slack"
                      url: "https://hooks.slack.com/services/T000/B000/XXX"
                      severities: ["critical"]
                  telegram_recipients: []
              TelegramAllSeverities:
                summary: Customer — Telegram channel on every severity
                description: |
                  Single Telegram bot pushing to a channel for every
                  severity (severities=[]). Telegram messages are
                  currently always rendered in English.
                value:
                  enabled: { email: null, webhook: null, telegram: true }
                  email_recipients: []
                  webhook_recipients: []
                  telegram_recipients:
                    - bot_token: "123456:ABC-DEF1234ghIkl"
                      chat_id: -1001234567890
                      severities: []
              InheritPurely:
                summary: Descendant — explicit "inherit everything"
                description: |
                  Saving an empty layer is meaningful: it just records
                  audit metadata (who/when) without contributing
                  recipients or toggles.
                value:
                  enabled: { email: null, webhook: null, telegram: null }
                  email_recipients: []
                  webhook_recipients: []
                  telegram_recipients: []
      responses:
        '200':
          description: Layer saved (and propagation attempted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alerting configuration updated successfully
                  data:
                    type: object
                    properties:
                      affected_tenants:
                        type: integer
                        description: Number of tenants in caller's hierarchy whose effective config was recomputed
                      propagated_to:
                        type: integer
                        description: Of `affected_tenants`, how many were successfully pushed to Mimir
                      warnings:
                        type: array
                        description: |
                          Per-tenant push errors. Always present; empty when every push succeeded.
                          Each entry: `org <logto_id>: <error>`.
                        items:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          description: Request body exceeds the configured maximum (1 MiB).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 413
                  message:
                    type: string
                    example: request body exceeds the configured maximum
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: disableAlerts
      tags:
        - Backend - Alerts Configuration
      summary: "/alerts/config - Remove the caller's alerting layer"
      description: |
        Removes the CALLER's layer from alert_config_layers. The effective
        config of all descendant tenants is recomputed without the caller's
        contribution and re-pushed to Mimir; ancestor layers are preserved.
        To completely silence a tenant, every layer in its chain must drop
        its contribution.

        Requires `manage:alerts` permission.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Layer removed (and propagation attempted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alerting layer removed successfully
                  data:
                    type: object
                    properties:
                      affected_tenants:
                        type: integer
                      propagated_to:
                        type: integer
                      warnings:
                        type: array
                        items:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: getAlertingConfig
      tags:
        - Backend - Alerts Configuration
      summary: "/alerts/config - Get the caller's alerting layer"
      description: |
        Returns the CALLER's own alerting configuration layer. No inherited
        ancestor layers, no merged effective view: every organization sees
        only its own configuration. The server-side merge that backs the
        Mimir YAML stays inside the backend.

        When the caller has never saved a layer the response body contains
        an empty layer (toggles all null, recipient lists empty) and the
        two audit fields set to null. The UI uses that state to render a
        first-save form.

        Requires `read:alerts` permission.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Caller's layer
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: alerting layer retrieved successfully
                  data:
                    allOf:
                      - $ref: '#/components/schemas/AlertingConfigLayer'
                      - type: object
                        properties:
                          updated_by_name:
                            type: string
                            nullable: true
                          updated_at:
                            type: string
                            format: date-time
                            nullable: true
              examples:
                Configured:
                  summary: Caller has saved a layer
                  value:
                    code: 200
                    message: "alerting layer retrieved successfully"
                    data:
                      enabled: { email: true, webhook: null, telegram: null }
                      email_recipients:
                        - address: "noc@reseller.example"
                          severities: ["critical"]
                          language: "it"
                          format: "html"
                      webhook_recipients: []
                      telegram_recipients: []
                      updated_by_name: "Reseller Admin"
                      updated_at: "2026-05-09T10:14:00Z"
                FirstTime:
                  summary: Caller has not saved a layer yet
                  value:
                    code: 200
                    message: "alerting layer retrieved successfully"
                    data:
                      enabled: { email: null, webhook: null, telegram: null }
                      email_recipients: []
                      webhook_recipients: []
                      telegram_recipients: []
                      updated_by_name: null
                      updated_at: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /alerts/config/effective:
    get:
      operationId: getEffectiveAlertingConfig
      tags:
        - Backend - Alerts Configuration
      summary: "/alerts/config/effective - Inspect a tenant's effective merged config"
      description: |
        Privileged troubleshooting view. Returns the configuration a tenant
        ACTUALLY receives: the per-layer contribution of every organization
        in its ancestor chain (Owner → tenant), the merged effective layer,
        and the rendered Alertmanager YAML pushed to Mimir for that tenant.

        Unlike `GET /alerts/config` (which returns only the caller's own
        layer), this exposes the full inherited + merged view, so it is
        gated by the dedicated `config:alerts` permission. That permission
        lives solely on the `super` user role, which is owner-assignable
        only — so in practice only an Owner-org Super Admin can reach this.
        It is not reachable by Distributor/Reseller admins.

        Secrets are redacted in the response: telegram `bot_token` and
        webhook URL path/query in every layer and in the effective layer,
        and SMTP credentials / bearer / bot tokens in the rendered YAML.

        `organization_id` is required and may target ANY tenant. A
        nonexistent id returns an empty effective config (no error) — the
        honest answer for a diagnostic tool. Read-only: no Mimir push, no
        DB writes.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          required: true
          schema:
            type: string
          description: Logto organization id of the tenant to inspect.
      responses:
        '200':
          description: Effective configuration report
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: effective alerting configuration retrieved successfully
                  data:
                    type: object
                    properties:
                      organization_id:
                        type: string
                      chain:
                        type: array
                        description: |
                          Contributing layers ordered Owner first → tenant
                          last. Orgs with no saved layer are listed with
                          `has_layer: false` and an empty layer.
                        items:
                          type: object
                          properties:
                            organization_id:
                              type: string
                            organization_name:
                              type: string
                            organization_role:
                              type: string
                              enum: [owner, distributor, reseller, customer]
                            has_layer:
                              type: boolean
                            layer:
                              $ref: '#/components/schemas/AlertingConfigLayer'
                            updated_by_name:
                              type: string
                              nullable: true
                            updated_at:
                              type: string
                              format: date-time
                              nullable: true
                      effective:
                        $ref: '#/components/schemas/AlertingConfigLayer'
                      yaml:
                        type: string
                        description: Rendered Alertmanager YAML (secrets redacted).
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /alerts/silences:
    get:
      operationId: getAlertSilences
      tags:
        - Backend - Alerts Silences
      summary: "/alerts/silences - List active+pending silences (hierarchy-wide)"
      description: |
        Cross-system parallel of `GET /systems/{id}/alerts/silences`. Returns
        every active or pending Alertmanager silence in the caller's scope,
        enriched with `organization_id` (the tenant that owns the silence) and
        `system_key` (extracted from the silence matchers). Expired silences
        and silences without a `system_key` matcher are excluded — only
        silences our UI ever creates are addressable.

        Scope follows the same three modes as `/alerts/totals`:
        - `organization_id` omitted → caller's full hierarchy (cross-tenant fan-out).
        - `organization_id=X` → single tenant `X`.
        - `organization_id=X&include=descendants` → `X` plus its sub-tree.

        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          description: |
            Target organization ID(s). Repeat the param for multiple values.
            Optional for all roles except Customer (where it is ignored).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: include
          in: query
          description: Set to `descendants` together with `organization_id` to expand each value to its sub-tree.
          schema:
            type: string
            enum: [descendants]
        - name: system_key
          in: query
          description: |
            Filter silences by one or more system keys (exact match on the
            `system_key` matcher). Repeat the param for multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Paginated list of system-scoped silences
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: silences retrieved successfully
                  data:
                    type: object
                    properties:
                      silences:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/AlertmanagerSilence'
                            - type: object
                              properties:
                                organization_id:
                                  type: string
                                  description: Tenant that owns the silence (Mimir stores silences per-tenant).
                                  example: "m4m3mdjdiizs"
                                system_key:
                                  type: string
                                  description: System key extracted from the silence matchers.
                                  example: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                      warnings:
                        type: array
                        description: |
                          Per-tenant fan-out errors. Always present (empty when
                          every tenant responded OK). Each entry is a string
                          `org <logto_id>: <error>`.
                        items:
                          type: string
              examples:
                OneActive:
                  summary: One active silence on a customer system
                  value:
                    code: 200
                    message: silences retrieved successfully
                    data:
                      silences:
                        - id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                          organization_id: "m4m3mdjdiizs"
                          system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          matchers:
                            - name: "system_key"
                              value: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                              isRegex: false
                            - name: "alertname"
                              value: "HighCPUUsage"
                              isRegex: false
                            - name: "severity"
                              value: "warning"
                              isRegex: false
                          startsAt: "2026-05-12T08:16:36Z"
                          endsAt: "2026-05-12T09:16:36Z"
                          updatedAt: "2026-05-12T08:16:36Z"
                          createdBy: "amelia.foster"
                          comment: "muted during maintenance window"
                          status:
                            state: "active"
                      warnings: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createAlertSilence
      tags:
        - Backend - Alerts Silences
      summary: "/alerts/silences - Mute an alert across systems"
      description: |
        Cross-system parallel of `POST /systems/{id}/alerts/silences`. Mutes
        an active alert identified by fingerprint inside a single tenant
        (`?organization_id=`). The backend looks up the alert in Mimir,
        extracts `system_key` from its labels, builds the matchers
        server-side, and delegates to the same silence-creation path used by
        the per-system endpoint — so the silence object stored in Mimir is
        byte-identical regardless of which route created it.

        If `end_at` is set it takes precedence over `duration_minutes`.

        Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: organization_id
          in: query
          required: true
          description: |
            Tenant that owns the alert. Mandatory for every role except
            Customer (where it is ignored — they're always pinned to their
            own organization). Owners can address any tenant in the system.
          schema:
            type: string
            example: "m4m3mdjdiizs"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fingerprint
              properties:
                fingerprint:
                  type: string
                  description: Fingerprint of the active alert to silence.
                  example: "0a9d04bb6eed523f"
                comment:
                  type: string
                  description: Optional silence comment. Defaults to a system-generated value when empty.
                  example: "silenced during maintenance"
                duration_minutes:
                  type: integer
                  minimum: 1
                  maximum: 10080
                  description: Optional duration in minutes. Defaults to 60 when omitted. Ignored when end_at is set.
                  example: 60
                end_at:
                  type: string
                  format: date-time
                  description: Optional explicit end time (RFC3339). Takes precedence over duration_minutes.
                  example: "2026-05-12T09:16:36Z"
            examples:
              ExplicitEndAt:
                summary: Silence until a specific date/time
                description: |
                  When `end_at` is set, the silence expires at that moment
                  regardless of `duration_minutes`. The backend resolves the
                  alert by `fingerprint` inside the tenant given by
                  `?organization_id=`, extracts `system_key` from its labels,
                  and creates the silence.
                value:
                  fingerprint: "0a9d04bb6eed523f"
                  comment: "silenced during maintenance window"
                  end_at: "2026-05-12T09:16:36Z"
              DurationBased:
                summary: Silence for the next 60 minutes
                description: |
                  Without `end_at`, `duration_minutes` applies. If both are
                  omitted, the silence defaults to 60 minutes from creation.
                value:
                  fingerprint: "0a9d04bb6eed523f"
                  comment: "investigating"
                  duration_minutes: 60
      responses:
        '200':
          description: Alert silenced successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "alert silenced successfully"
                  data:
                    type: object
                    properties:
                      silence_id:
                        type: string
                        example: "d9f91c6e-1b33-484e-befa-bfb41020e178"
              examples:
                Created:
                  summary: Silence created
                  description: |
                    `silence_id` is the Alertmanager-assigned UUID; use it to
                    look up, update, or delete the silence later. The
                    corresponding `silenced` event is appended to the alert's
                    activity timeline (`GET /alerts/activity/{fingerprint}`).
                  value:
                    code: 200
                    message: "alert silenced successfully"
                    data:
                      silence_id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /alerts/silences/{silence_id}:
    get:
      operationId: getAlertSilence
      tags:
        - Backend - Alerts Silences
      summary: "/alerts/silences/{silence_id} - Get a single silence"
      description: |
        Cross-system parallel of `GET /systems/{id}/alerts/silences/{silence_id}`.
        Looks up a silence inside a single tenant (`?organization_id=`) and
        returns it enriched with `organization_id` and `system_key`. Silences
        without a `system_key` matcher are reported as 404 — they don't belong
        to our domain.

        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: silence_id
          in: path
          required: true
          description: Alertmanager silence ID.
          schema:
            type: string
            example: "d9f91c6e-1b33-484e-befa-bfb41020e178"
        - name: organization_id
          in: query
          required: true
          description: |
            Tenant that owns the silence. Mandatory for every role except
            Customer (where it is ignored).
          schema:
            type: string
            example: "m4m3mdjdiizs"
      responses:
        '200':
          description: Silence retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence retrieved successfully"
                  data:
                    type: object
                    properties:
                      silence:
                        allOf:
                          - $ref: '#/components/schemas/AlertmanagerSilence'
                          - type: object
                            properties:
                              organization_id:
                                type: string
                                example: "m4m3mdjdiizs"
                              system_key:
                                type: string
                                example: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
              examples:
                ActiveSilence:
                  summary: Silence found and active
                  description: |
                    Same `AlertmanagerSilence` shape as the per-system
                    endpoint, plus `organization_id` (the tenant that owns the
                    silence) and `system_key` (extracted from the matchers).
                  value:
                    code: 200
                    message: "silence retrieved successfully"
                    data:
                      silence:
                        id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                        organization_id: "m4m3mdjdiizs"
                        system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                        matchers:
                          - name: "system_key"
                            value: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                            isRegex: false
                          - name: "alertname"
                            value: "HighCPUUsage"
                            isRegex: false
                          - name: "severity"
                            value: "warning"
                            isRegex: false
                        startsAt: "2026-05-12T08:16:36Z"
                        endsAt: "2026-05-12T09:16:36Z"
                        updatedAt: "2026-05-12T08:16:36Z"
                        createdBy: "amelia.foster"
                        comment: "silenced during maintenance window"
                        status:
                          state: "active"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAlertSilence
      tags:
        - Backend - Alerts Silences
      summary: "/alerts/silences/{silence_id} - Update a silence"
      description: |
        Cross-system parallel of `PUT /systems/{id}/alerts/silences/{silence_id}`.
        Preserves the original matchers and start time; only `end_at` and
        `comment` change. Refuses to operate on silences without a
        `system_key` matcher (404). Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: silence_id
          in: path
          required: true
          schema:
            type: string
            example: "d9f91c6e-1b33-484e-befa-bfb41020e178"
        - name: organization_id
          in: query
          required: true
          schema:
            type: string
            example: "m4m3mdjdiizs"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - end_at
              properties:
                comment:
                  type: string
                  example: "extended for maintenance window"
                end_at:
                  type: string
                  format: date-time
                  example: "2026-05-12T12:16:36Z"
            examples:
              ExtendEndTime:
                summary: Extend the silence by 3 more hours
                description: |
                  Alertmanager treats an update as "create a new silence with
                  the same matchers and start_at, then drop the old one", so
                  the response carries a new `silence_id`. The activity
                  timeline records this as a `silence_updated` event.
                value:
                  comment: "extended for maintenance window"
                  end_at: "2026-05-12T12:16:36Z"
      responses:
        '200':
          description: Silence updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence updated successfully"
                  data:
                    type: object
                    properties:
                      silence_id:
                        type: string
                        example: "f1e1c2a4-7e57-4b1a-aaa0-2b96c8b5a3aa"
              examples:
                Updated:
                  summary: New silence id after update
                  description: |
                    The `silence_id` differs from the one passed in the path:
                    Alertmanager replaced the silence under the hood while
                    preserving its matchers and start time.
                  value:
                    code: 200
                    message: "silence updated successfully"
                    data:
                      silence_id: "f1e1c2a4-7e57-4b1a-aaa0-2b96c8b5a3aa"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAlertSilence
      tags:
        - Backend - Alerts Silences
      summary: "/alerts/silences/{silence_id} - Unmute an alert (delete silence)"
      description: |
        Cross-system parallel of `DELETE /systems/{id}/alerts/silences/{silence_id}`.
        Removes a system-scoped silence; generic Alertmanager silences (no
        `system_key` matcher) are not addressable through this endpoint and
        return 404. Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: silence_id
          in: path
          required: true
          schema:
            type: string
            example: "d9f91c6e-1b33-484e-befa-bfb41020e178"
        - name: organization_id
          in: query
          required: true
          schema:
            type: string
            example: "m4m3mdjdiizs"
      responses:
        '200':
          description: Silence disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence disabled successfully"
              examples:
                Disabled:
                  summary: Silence removed
                  description: |
                    The silence is deleted from Alertmanager but stays
                    referenced in the alert's activity timeline as an
                    `unsilenced` event (`GET /alerts/activity/{fingerprint}`).
                  value:
                    code: 200
                    message: "silence disabled successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================
  # ALERTING ENDPOINTS (Backend - Configuration)
  # ===========================================

  /systems/{id}/alerts:
    get:
      operationId: getSystemAlerts
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts - Get active alerts for a system"
      description: |
        Returns current alerts from Mimir scoped to a single system. Mirrors
        the filter, pagination, and sort surface of `GET /alerts`: the only
        difference is that `system_key` is pinned to the URL path (the
        multi-value `system_key` query filter is therefore not exposed).
        Suppressed alerts remain visible so silenced alerts can still be
        inspected in the system detail view.

        System identity is carried as labels on each alert (`system_id`,
        `system_key`, `system_name`, `system_type`), stamped at ingest time.

        Multi-value filters: OR within the same filter, AND across filters.

        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Page size. Default 50, max 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: sort_by
          in: query
          description: Sort column (allowlist matches `/alerts`).
          schema:
            type: string
            enum: [starts_at, severity, alertname, status]
            default: starts_at
        - name: sort_direction
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: status
          in: query
          description: Filter by Alertmanager state. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [active, suppressed, unprocessed]
          style: form
          explode: true
        - name: severity
          in: query
          description: Filter by severity. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [critical, warning, info]
          style: form
          explode: true
        - name: alertname
          in: query
          description: Filter by alertname. Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Active alerts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "alerts retrieved successfully"
                  data:
                    type: object
                    properties:
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/ActiveAlert'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
              examples:
                ActiveAndSuppressedOnSystem:
                  summary: Two firing alerts on the same system, one silenced
                  description: |
                    The endpoint always includes silenced alerts so the UI can
                    show the muted state in the system detail view. `state` is
                    `"suppressed"` when at least one active silence matches the
                    alert; the matching silence IDs are listed in `silencedBy`.
                  value:
                    code: 200
                    message: "alerts retrieved successfully"
                    data:
                      alerts:
                        - fingerprint: "0a9d04bb6eed523f"
                          labels:
                            alertname: "DiskFilling"
                            severity: "warning"
                            system_id: "e4eb4844-46f6-448c-8279-7cfedf5e1037"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                            system_name: "test-sys"
                            system_type: "ns8"
                          annotations:
                            summary: "/var is 92% full"
                            description: "Disk usage exceeded warning threshold."
                          status:
                            state: "suppressed"
                            silencedBy:
                              - "d9f91c6e-1b33-484e-befa-bfb41020e178"
                            inhibitedBy: []
                          startsAt: "2026-05-12T08:14:00Z"
                          endsAt: "2026-05-12T08:44:00Z"
                        - fingerprint: "11a9302b0fa6526e"
                          labels:
                            alertname: "HighCPU"
                            severity: "critical"
                            system_id: "e4eb4844-46f6-448c-8279-7cfedf5e1037"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                            system_name: "test-sys"
                            system_type: "ns8"
                          annotations:
                            summary: "CPU usage 98%"
                            description: "Sustained high CPU."
                          status:
                            state: "active"
                            silencedBy: []
                            inhibitedBy: []
                          startsAt: "2026-05-12T08:20:00Z"
                          endsAt: "2026-05-12T08:50:00Z"
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 2
                        total_pages: 1
                        has_next: false
                        has_prev: false
                        sort_by: "starts_at"
                        sort_direction: "desc"
                NoActiveAlerts:
                  summary: System has no firing alerts
                  value:
                    code: 200
                    message: "alerts retrieved successfully"
                    data:
                      alerts: []
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 0
                        total_pages: 0
                        has_next: false
                        has_prev: false
                        sort_by: "starts_at"
                        sort_direction: "desc"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/alerts/history:
    get:
      operationId: getSystemAlertHistory
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/history - Get system alert history"
      description: |
        Get paginated history of resolved and inactive alerts for a specific system.
        Alerts are stored by the collect service when Alertmanager sends webhook notifications.
        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (logto_id)
          schema:
            type: string
            example: "sys_123456789"
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: sort_by
          in: query
          required: false
          description: Field to sort by
          schema:
            type: string
            enum: [id, alertname, severity, status, starts_at, ends_at, created_at]
            default: created_at
        - name: sort_direction
          in: query
          required: false
          description: |
            Sort direction. Unlike the shared default of `asc`, this endpoint
            defaults to `desc` so the natural "most recent first" ordering is
            applied when the caller omits the param.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: from_date
          in: query
          required: false
          description: Lower bound on `created_at` (inclusive). RFC3339 timestamp.
          schema:
            type: string
            format: date-time
            example: "2026-05-01T00:00:00Z"
        - name: to_date
          in: query
          required: false
          description: Upper bound on `created_at` (exclusive). RFC3339 timestamp. Must be after `from_date`.
          schema:
            type: string
            format: date-time
            example: "2026-05-08T00:00:00Z"
        - name: alertname
          in: query
          required: false
          description: Filter by alertname. Supports multiple values (OR within filter).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: severity
          in: query
          required: false
          description: Filter by severity. Supports multiple values.
          schema:
            type: array
            items:
              type: string
              enum: [critical, warning, info]
          style: form
          explode: true
        - name: status
          in: query
          required: false
          description: Filter by status. Supports multiple values.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Alert history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "alert history retrieved successfully"
                  data:
                    type: object
                    properties:
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/AlertHistoryRecord'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
              examples:
                ResolvedAlertsForSystem:
                  summary: Two resolved alerts on this system
                  description: |
                    Records are scoped to the path system's `system_key`. The
                    response is identical in shape to `GET /alerts/history` but
                    filtered to one system without needing to pass it as a
                    query param.
                  value:
                    code: 200
                    message: "alert history retrieved successfully"
                    data:
                      alerts:
                        - id: 55
                          organization_id: "m4m3mdjdiizs"
                          system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          alertname: "PlainBodyTest"
                          severity: "critical"
                          status: "resolved"
                          fingerprint: "11a9302b0fa6526e"
                          starts_at: "2026-05-12T07:46:50Z"
                          ends_at: "2026-05-12T07:51:50Z"
                          summary: "plain body check"
                          labels:
                            alertname: "PlainBodyTest"
                            severity: "critical"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          annotations:
                            summary: "plain body check"
                            description: "resolved"
                          receiver: "severity-critical-receiver"
                          created_at: "2026-05-12T07:52:00Z"
                        - id: 54
                          organization_id: "m4m3mdjdiizs"
                          system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          alertname: "HistFlowTest"
                          severity: "critical"
                          status: "resolved"
                          fingerprint: "9c1a23e87f4d0a11"
                          starts_at: "2026-05-12T08:01:07Z"
                          ends_at: "2026-05-12T08:06:06Z"
                          summary: "history flow check"
                          labels:
                            alertname: "HistFlowTest"
                            severity: "critical"
                            system_key: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                          annotations:
                            summary: "history flow check"
                            description: "resolved"
                          receiver: "severity-critical-receiver"
                          created_at: "2026-05-12T08:11:30Z"
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 2
                        total_pages: 1
                        has_next: false
                        has_prev: false
                EmptyHistory:
                  summary: No history rows for this system yet
                  value:
                    code: 200
                    message: "alert history retrieved successfully"
                    data:
                      alerts: []
                      pagination:
                        page: 1
                        page_size: 50
                        total_count: 0
                        total_pages: 0
                        has_next: false
                        has_prev: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================================================
  # SYSTEM BACKUPS
  # ===========================================================================

  /systems/{id}/alerts/silences:
    get:
      operationId: getSystemAlertSilences
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/silences - List active silences for a system"
      description: |
        Returns all active and pending Alertmanager silences scoped to the target system.
        Expired silences are excluded. Results are filtered server-side to silences that carry
        an exact `system_key` matcher matching the system's key.
        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Silences retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silences retrieved successfully"
                  data:
                    type: object
                    properties:
                      silences:
                        type: array
                        items:
                          $ref: '#/components/schemas/AlertmanagerSilence'
              examples:
                ActiveSilence:
                  summary: One active silence for the system
                  description: |
                    The silence matches on `system_key` (server-injected) plus the
                    labels that uniquely identified the alert at silence creation
                    time. `silencedBy` on the active alert references this same
                    `id`.
                  value:
                    code: 200
                    message: "silences retrieved successfully"
                    data:
                      silences:
                        - id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                          matchers:
                            - name: "system_key"
                              value: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                              isRegex: false
                            - name: "alertname"
                              value: "DiskFilling"
                              isRegex: false
                            - name: "severity"
                              value: "warning"
                              isRegex: false
                          startsAt: "2026-05-12T08:16:36Z"
                          endsAt: "2026-05-12T09:16:36Z"
                          updatedAt: "2026-05-12T08:16:36Z"
                          createdBy: "R1C1 Admin <c5gpnoo2do48>"
                          comment: "silenced during maintenance window"
                          status:
                            state: "active"
                NoSilences:
                  summary: No silences for the system
                  value:
                    code: 200
                    message: "silences retrieved successfully"
                    data:
                      silences: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createSystemAlertSilence
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/silences - Create a silence for a system alert"
      description: |
        Creates an Alertmanager silence for a specific active alert on the target system.
        The request identifies the live alert by fingerprint. The backend resolves the alert,
        builds the silence matchers server-side, and always uses the system's authoritative
        `system_key`.
        If `end_at` is provided it takes precedence over `duration_minutes`.
        Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fingerprint
              properties:
                fingerprint:
                  type: string
                  description: Fingerprint of the active alert to silence
                  example: "8f2d65896d4bcf97"
                comment:
                  type: string
                  description: Optional silence comment. Defaults to a system-generated value when empty.
                  example: "silenced during maintenance"
                duration_minutes:
                  type: integer
                  minimum: 1
                  maximum: 10080
                  description: Optional silence duration in minutes. Defaults to 60 when omitted. Ignored when end_at is set.
                  example: 60
                end_at:
                  type: string
                  format: date-time
                  description: Optional explicit end time (RFC3339). Takes precedence over duration_minutes.
                  example: "2024-01-01T02:00:00Z"
            examples:
              ExplicitEndAt:
                summary: Silence until a specific date/time
                description: |
                  When `end_at` is set, the silence expires at that moment
                  regardless of `duration_minutes`. The backend resolves the
                  alert by `fingerprint`, attaches the system's authoritative
                  `system_key` to the matchers, and creates the silence.
                value:
                  fingerprint: "0a9d04bb6eed523f"
                  comment: "silenced during maintenance window"
                  end_at: "2026-05-12T09:16:36Z"
              DurationBased:
                summary: Silence for the next 60 minutes
                description: |
                  Without `end_at`, `duration_minutes` applies. If both are
                  omitted, the silence defaults to 60 minutes from creation.
                value:
                  fingerprint: "0a9d04bb6eed523f"
                  comment: "investigating"
                  duration_minutes: 60
      responses:
        '200':
          description: Alert silence created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "alert silenced successfully"
                  data:
                    type: object
                    properties:
                      silence_id:
                        type: string
                        example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
              examples:
                Created:
                  summary: Silence created
                  description: |
                    `silence_id` is the Alertmanager-assigned UUID; use it to
                    look up, update, or delete the silence later. The
                    corresponding `silenced` event is appended to the alert's
                    activity timeline (`GET /alerts/activity/{fingerprint}`).
                  value:
                    code: 200
                    message: "alert silenced successfully"
                    data:
                      silence_id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/alerts/silences/{silence_id}:
    get:
      operationId: getSystemAlertSilence
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/silences/{silence_id} - Get a single silence"
      description: |
        Returns a specific Alertmanager silence after verifying it belongs to the target system
        via its `system_key` matcher.
        Requires `read:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
        - name: silence_id
          in: path
          required: true
          description: Alertmanager silence ID
          schema:
            type: string
            example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
      responses:
        '200':
          description: Silence retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence retrieved successfully"
                  data:
                    type: object
                    properties:
                      silence:
                        $ref: '#/components/schemas/AlertmanagerSilence'
              examples:
                ActiveSilence:
                  summary: Silence found and active
                  value:
                    code: 200
                    message: "silence retrieved successfully"
                    data:
                      silence:
                        id: "d9f91c6e-1b33-484e-befa-bfb41020e178"
                        matchers:
                          - name: "system_key"
                            value: "NETH-D417-A2C2-7810-43D2-984B-2164-34C1-B22E"
                            isRegex: false
                          - name: "alertname"
                            value: "DiskFilling"
                            isRegex: false
                          - name: "severity"
                            value: "warning"
                            isRegex: false
                        startsAt: "2026-05-12T08:16:36Z"
                        endsAt: "2026-05-12T09:16:36Z"
                        updatedAt: "2026-05-12T08:16:36Z"
                        createdBy: "R1C1 Admin <c5gpnoo2do48>"
                        comment: "silenced during maintenance window"
                        status:
                          state: "active"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSystemAlertSilence
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/silences/{silence_id} - Update a silence"
      description: |
        Updates the end time and/or comment of an existing silence. Preserves the original
        matchers and start time. Ownership is verified via the `system_key` matcher.
        Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
        - name: silence_id
          in: path
          required: true
          description: Alertmanager silence ID
          schema:
            type: string
            example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - end_at
              properties:
                comment:
                  type: string
                  description: New comment for the silence. Defaults to previous value if empty.
                  example: "extended for maintenance window"
                end_at:
                  type: string
                  format: date-time
                  description: New end time (RFC3339). Must be in the future.
                  example: "2024-01-01T04:00:00Z"
            examples:
              ExtendEndTime:
                summary: Extend the silence by 3 more hours
                description: |
                  Alertmanager treats an update as "create a new silence with
                  the same matchers and start_at, then drop the old one", so
                  the response carries a new `silence_id`. The activity
                  timeline records this as a `silence_updated` event.
                value:
                  comment: "extended for maintenance window"
                  end_at: "2026-05-12T12:16:36Z"
      responses:
        '200':
          description: Silence updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence updated successfully"
                  data:
                    type: object
                    properties:
                      silence_id:
                        type: string
                        example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
              examples:
                Updated:
                  summary: New silence id after update
                  value:
                    code: 200
                    message: "silence updated successfully"
                    data:
                      silence_id: "f1e1c2a4-7e57-4b1a-aaa0-2b96c8b5a3aa"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSystemAlertSilence
      tags:
        - Backend - Alerts (Per-System)
      summary: "/systems/{id}/alerts/silences/{silence_id} - Disable a system alert silence"
      description: |
        Deletes a system-scoped Alertmanager silence after validating that the silence belongs
        to the target system through the authoritative `system_key` matcher.
        Requires `manage:systems` permission.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: System ID (database UUID)
          schema:
            type: string
            example: "sys_123456789"
        - name: silence_id
          in: path
          required: true
          description: Alertmanager silence ID
          schema:
            type: string
            example: "4e6f0c30-c383-4e22-9443-0d7b6a8bd40b"
      responses:
        '200':
          description: Alert silence disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "silence disabled successfully"
              examples:
                Disabled:
                  summary: Silence removed
                  description: |
                    The silence is expired (not hard-deleted) so it disappears
                    from `GET /silences` but stays referenced in the alert's
                    activity timeline as an `unsilenced` event. On the wire
                    the response also carries `"data": null`; the example
                    omits it to match the declared schema which only includes
                    `code` and `message`.
                  value:
                    code: 200
                    message: "silence disabled successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /systems/{id}/backups:
    get:
      operationId: getSystemBackups
      tags:
        - Backend - Systems Backups
      summary: /systems/{id}/backups - List configuration backups for a system
      description: |
        Returns the list of configuration backups stored for the system,
        together with aggregate usage counters. Backups are produced by
        the appliance itself (see collect ingest endpoint) and consumed
        here read-only.

        Each entry carries `size`, `sha256`, and `uploaded_at`. The
        peer IP observed at ingest is intentionally not exposed: on
        traffic that transits the translation proxy the recorded value
        would be the proxy's IP, and even when it is accurate it is a
        reconnaissance aid for higher-tier admins.

        Access is gated by the same RBAC rules as `GET /systems/{id}`:
        the caller must belong to the organization that currently owns
        the system. After a cross-org reassignment, the new owner sees
        the full backup list and the previous owner loses visibility.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
      responses:
        '200':
          description: Backups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "backups retrieved successfully"
                  data:
                    type: object
                    properties:
                      backups:
                        type: array
                        items:
                          $ref: '#/components/schemas/BackupMetadata'
                      quota_used_bytes:
                        type: integer
                        format: int64
                        description: Sum of backup sizes stored for this system
                        example: 314572800
                      slots_used:
                        type: integer
                        description: Number of backups currently stored
                        example: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          description: Backup storage unreachable or returned an error
        '503':
          description: Backup storage is not configured

  /systems/{id}/backups/{backup_id}/download:
    get:
      operationId: downloadSystemBackup
      tags:
        - Backend - Systems Backups
      summary: /systems/{id}/backups/{backup_id}/download - Issue a short-lived download URL
      description: |
        Returns a short-lived presigned S3 URL that the user's browser
        uses to stream the backup object directly from storage. The API
        never proxies the object body itself.

        The backend does not perform a redirect because the frontend
        sends its JWT on the initial request — browsers would drop the
        `Authorization` header when following a 3xx redirect, so the
        frontend receives the URL in the JSON response and navigates to
        it explicitly.

        The presigned URL's lifetime is controlled by the
        `BACKUP_PRESIGN_TTL` environment variable (default 5 minutes).

        Access is gated by the same RBAC rules as `GET /systems/{id}`.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - name: backup_id
          in: path
          required: true
          description: Backup object ID (UUIDv7 + extension, e.g. "01934f...tar.gz")
          schema:
            type: string
            example: "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz"
      responses:
        '200':
          description: Download URL issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "download URL issued"
                  data:
                    type: object
                    properties:
                      download_url:
                        type: string
                        format: uri
                        description: Short-lived presigned S3 URL
                      expires_in_seconds:
                        type: integer
                        description: How long the URL remains valid
                        example: 300
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          description: Backup storage unreachable or returned an error
        '503':
          description: Backup storage is not configured

    delete:
      operationId: deleteSystemBackup
      tags:
        - Backend - Systems Backups
      summary: /systems/{id}/backups/{backup_id} - Delete a stored backup
      description: |
        Deletes a backup object from storage. The operation is final —
        storage uses object-level deletion, not a soft-delete table.

        Access is gated by the same RBAC rules as `GET /systems/{id}`.
      parameters:
        - name: id
          in: path
          required: true
          description: System ID
          schema:
            type: string
            example: "sys_123456789"
        - name: backup_id
          in: path
          required: true
          description: Backup object ID
          schema:
            type: string
            example: "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz"
      responses:
        '200':
          description: Backup deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "backup deleted"
                  data:
                    type: object
                    properties:
                      system_id:
                        type: string
                        example: "sys_123456789"
                      backup_id:
                        type: string
                        example: "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          description: Backup storage unreachable or returned an error
        '503':
          description: Backup storage is not configured

  # ===========================================================================
  # APPLICATIONS MANAGEMENT
  # ===========================================================================
  /applications:
    get:
      operationId: getApplications
      tags:
        - Backend - Applications
      summary: /applications - List applications
      description: |
        Get list of system applications visible to the user based on hierarchical organization permissions.
        Supports filtering by type, version, system, organization, and status.

        **Query String Examples:**

        1. **Single type filter**: `?type=mail`
        2. **Multiple types filter**: `?type=mail&type=webtop`
        3. **Status filter**: `?status=unassigned`
        4. **With pagination and sorting**: `?page=1&page_size=50&sort_by=instance_of&sort_direction=asc`
        5. **Combined filters**: `?type=mail&status=assigned&organization_id=org_abc123`
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/AppSortByParam'
        - $ref: '#/components/parameters/SortDirectionParam'
        - $ref: '#/components/parameters/AppTypeFilterParam'
        - $ref: '#/components/parameters/AppVersionFilterParam'
        - $ref: '#/components/parameters/AppSystemFilterParam'
        - $ref: '#/components/parameters/AppOrganizationFilterParam'
        - $ref: '#/components/parameters/AppStatusFilterParam'
      responses:
        '200':
          description: Applications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "applications retrieved successfully"
                  data:
                    type: object
                    properties:
                      applications:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApplicationListItem'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /applications/totals:
    get:
      operationId: getApplicationTotals
      tags:
        - Backend - Applications Stats
      summary: /applications/totals - Get application statistics
      description: Get statistics about applications including counts by type and status
      responses:
        '200':
          description: Application totals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application totals retrieved successfully"
                  data:
                    $ref: '#/components/schemas/ApplicationTotals'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /applications/summary:
    get:
      operationId: getApplicationTypeSummary
      tags:
        - Backend - Applications Stats
      summary: /applications/summary - Get applications grouped by type
      description: |
        Returns applications grouped by instance_of (type) with a counter.
        Hierarchically authorized: the caller only sees applications on systems within their organization tree.
        Optionally filterable by organization_id to restrict to a specific organization or by system_id to restrict to a specific system.
        When include_hierarchy is true, also includes applications from all child organizations.
      parameters:
        - name: organization_id
          in: query
          required: false
          description: Logto ID of a specific organization to filter by. Must be within the caller's hierarchy.
          schema:
            type: string
        - name: system_id
          in: query
          required: false
          description: UUID of a specific system to filter by. Must be within the caller's hierarchy.
          schema:
            type: string
        - name: include_hierarchy
          in: query
          required: false
          description: When true (and organization_id is provided), includes applications from all child organizations in the hierarchy
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          required: false
          description: Page number for paginating the by_type array (1-based). If omitted, all types are returned.
          schema:
            type: integer
            minimum: 1
        - name: page_size
          in: query
          required: false
          description: Number of application types per page (max 100). If omitted, all types are returned.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: sort_by
          in: query
          required: false
          description: Field to sort by_type results by
          schema:
            type: string
            enum: [count, created_at, instance_of]
            default: count
        - name: sort_direction
          in: query
          required: false
          description: Sort direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Application type summary retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application type summary retrieved successfully"
                  data:
                    $ref: '#/components/schemas/ApplicationTypeSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /applications/trend:
    get:
      operationId: getApplicationsTrend
      tags:
        - Backend - Applications Stats
      summary: /applications/trend - Get applications trend data
      description: Get trend data for applications over a specified period showing daily counts
      parameters:
        - name: period
          in: query
          required: false
          description: Number of days to include in trend data (default 7, max 365)
          schema:
            type: integer
            default: 7
            minimum: 1
            maximum: 365
      responses:
        '200':
          description: Applications trend data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "applications trend retrieved successfully"
                  data:
                    $ref: '#/components/schemas/TrendResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /filters/applications:
    get:
      operationId: getApplicationFilters
      tags:
        - Backend - Filters
      summary: /filters/applications - Get aggregated application filters
      description: |
        Aggregated endpoint that returns all application filter data in a single request.
        RBAC is resolved once, then types, versions, systems, and organizations are fetched in parallel.

        **Version Format**: Returns versions in prefixed format `type:version` (e.g., `"nethvoice:1.5.3"`, `"mail:1.7.4"`)

        **Organizations special value**: If there are applications without an assigned organization, the response includes
        a special "No organization" entry with `id: "no_org"` and `type: "unassigned"`.
      responses:
        '200':
          description: Application filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application filters retrieved successfully"
                  data:
                    type: object
                    properties:
                      types:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApplicationType'
                      versions:
                        type: array
                        items:
                          type: object
                          properties:
                            application:
                              type: string
                              description: Application type (instance_of)
                              example: "nethvoice"
                            name:
                              type: string
                              description: Human-readable application name
                              example: "NethVoice"
                            versions:
                              type: array
                              items:
                                type: string
                              description: Prefixed versions (type:version)
                              example: ["nethvoice:1.5.4", "nethvoice:1.5.3"]
                      systems:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApplicationSystemSummary'
                      organizations:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrganizationSummary'
              example:
                code: 200
                message: "application filters retrieved successfully"
                data:
                  types:
                    - instance_of: "nethvoice"
                      name: "NethVoice"
                      count: 15
                    - instance_of: "mail"
                      name: "Mail"
                      count: 8
                  versions:
                    - application: "mail"
                      name: "Mail"
                      versions: ["mail:1.7.4"]
                    - application: "nethvoice"
                      name: "NethVoice"
                      versions: ["nethvoice:1.5.4", "nethvoice:1.5.3"]
                  systems:
                    - id: "abc123-system-uuid"
                      name: "Production Server"
                    - id: "def456-system-uuid"
                      name: "Development Server"
                  organizations:
                    - id: "no_org"
                      logto_id: "no_org"
                      name: "No organization"
                      description: ""
                      type: "unassigned"
                    - id: "8b04e253-d408-4218-a30e-b048196847e5"
                      logto_id: "fso3biosnaqp"
                      name: "Acme Corp"
                      description: ""
                      type: "customer"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /filters/users:
    get:
      operationId: getUserFilters
      tags:
        - Backend - Filters
      summary: /filters/users - Get aggregated user filters
      description: |
        Aggregated endpoint that returns all user filter data in a single request.
        Auth is checked once, then roles and organizations are fetched in parallel.
        Respects RBAC hierarchy for both roles and organizations.
      responses:
        '200':
          description: User filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user filters retrieved successfully"
                  data:
                    type: object
                    properties:
                      roles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Role'
                      organizations:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Organization Logto ID
                              example: "org_abc123"
                            name:
                              type: string
                              description: Organization name
                              example: "ACME Corp"
                            type:
                              type: string
                              enum: [distributor, reseller, customer]
                              description: Organization type
                              example: "customer"
              example:
                code: 200
                message: "user filters retrieved successfully"
                data:
                  roles:
                    - id: "role_abc123"
                      name: "Admin"
                      description: "System administrator"
                    - id: "role_def456"
                      name: "Support"
                      description: "Support operator"
                  organizations:
                    - id: "org_abc123"
                      name: "ACME Corp"
                      type: "customer"
                    - id: "org_def456"
                      name: "TechStart Inc"
                      type: "reseller"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /filters/alerts:
    get:
      operationId: getAlertFilters
      tags:
        - Backend - Filters
      summary: /filters/alerts - Get aggregated alert filters
      description: |
        Aggregated endpoint for the alerts views' filter dropdowns.

        `systems`, `severities` and `organizations` are data-driven: only
        values that actually appear in alert history within the caller's scope
        are returned. `alerts` is a static catalog of every alert a NethServer
        (NS8) or NethSecurity system can raise — it is NOT scoped to the
        caller's data, so the dropdown can filter on alerts not yet received.

        Auth is checked once, then the data-driven datasets are fetched in
        parallel.

        Scope follows the same rules as the other alerts endpoints:
        `organization_id` omitted = caller's full hierarchy; one or more
        `organization_id` = those tenants (validated, Owner exempt);
        Customer is always pinned to its own organization.
      parameters:
        - name: organization_id
          in: query
          required: false
          description: |
            Tenant scope. Omit for the caller's full hierarchy, or repeat to
            target specific tenants (each validated against the caller's
            hierarchy; Owner exempt).
          schema:
            type: array
            items:
              type: string
          example: ["org_abc123"]
        - name: include
          in: query
          required: false
          description: When set to `descendants`, expand each organization_id to itself plus its sub-tree.
          schema:
            type: string
            enum: [descendants]
      responses:
        '200':
          description: Alert filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "alert filters retrieved successfully"
                  data:
                    type: object
                    properties:
                      systems:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: System local ID
                              example: "sys_abc123"
                            name:
                              type: string
                              description: System display name
                              example: "Milan Office Server"
                            type:
                              type: string
                              description: System type (empty string if unknown)
                              example: "ns8"
                            key:
                              type: string
                              description: Unique system key
                              example: "ABCD1234"
                      alerts:
                        type: array
                        description: |
                          Static catalog of every alert a NethServer (NS8) or
                          NethSecurity system can raise. Not scoped to the
                          caller's data — returned in full regardless of what
                          alert history exists.
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Alert name (alertname label)
                              example: "DiskSpaceLow"
                            severity:
                              type: string
                              enum: [critical, warning, info]
                              description: Default severity for this alert type
                              example: "warning"
                            service:
                              type: string
                              description: Sub-service that raises the alert (omitted when not applicable)
                              example: "storage"
                      severities:
                        type: array
                        items:
                          type: string
                        description: Distinct severities present in alert history
                        example: ["critical", "warning"]
                      organizations:
                        type: array
                        items:
                          type: object
                          properties:
                            logto_id:
                              type: string
                              description: Organization Logto ID
                              example: "org_abc123"
                            name:
                              type: string
                              description: Organization name
                              example: "ACME Corp"
                            type:
                              type: string
                              enum: [distributor, reseller, customer]
                              description: Organization type
                              example: "customer"
              example:
                code: 200
                message: "alert filters retrieved successfully"
                data:
                  systems:
                    - id: "sys_abc123"
                      name: "Milan Office Server"
                      type: "ns8"
                      key: "ABCD1234"
                  alerts:
                    - name: "DiskSpaceLow"
                      severity: "warning"
                      service: "storage"
                    - name: "ServiceDown"
                      severity: "critical"
                  severities:
                    - "critical"
                    - "warning"
                  organizations:
                    - logto_id: "org_abc123"
                      name: "ACME Corp"
                      type: "customer"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /applications/{id}:
    get:
      operationId: getApplicationById
      tags:
        - Backend - Applications
      summary: /applications/{id} - Get single application
      description: Get a specific application by ID
      parameters:
        - name: id
          in: path
          required: true
          description: Application ID
          schema:
            type: string
            example: "sys_abc123_mail1"
      responses:
        '200':
          description: Application retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application retrieved successfully"
                  data:
                    $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      operationId: updateApplication
      tags:
        - Backend - Applications
      summary: /applications/{id} - Update application
      description: Update an application's notes (other fields are read-only and populated from inventory)
      parameters:
        - name: id
          in: path
          required: true
          description: Application ID
          schema:
            type: string
            example: "sys_abc123_mail1"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApplicationRequest'
      responses:
        '200':
          description: Application updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application updated successfully"
                  data:
                    $ref: '#/components/schemas/Application'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteApplication
      tags:
        - Backend - Applications
      summary: /applications/{id} - Delete application
      description: Soft-delete an application
      parameters:
        - name: id
          in: path
          required: true
          description: Application ID
          schema:
            type: string
            example: "sys_abc123_mail1"
      responses:
        '200':
          description: Application deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "application deleted successfully"
                  data:
                    type: object
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /applications/{id}/assign:
    patch:
      operationId: assignApplicationOrganization
      tags:
        - Backend - Applications
      summary: /applications/{id}/assign - Assign organization
      description: Assign an organization to an application
      parameters:
        - name: id
          in: path
          required: true
          description: Application ID
          schema:
            type: string
            example: "sys_abc123_mail1"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignApplicationRequest'
      responses:
        '200':
          description: Organization assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "organization assigned successfully"
                  data:
                    $ref: '#/components/schemas/Application'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /applications/{id}/unassign:
    patch:
      operationId: unassignApplicationOrganization
      tags:
        - Backend - Applications
      summary: /applications/{id}/unassign - Remove organization
      description: Remove organization assignment from an application
      parameters:
        - name: id
          in: path
          required: true
          description: Application ID
          schema:
            type: string
            example: "sys_abc123_mail1"
      responses:
        '200':
          description: Organization unassigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "organization unassigned successfully"
                  data:
                    $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================================================
  # OAUTH2/OIDC STANDARD ENDPOINTS (Third-party Applications)
  # ===========================================================================
  /user/permissions:
    get:
      operationId: getUserPermissions
      tags:
        - Backend - User
      summary: /user/permissions - Get user permissions (OAuth2/OIDC)
      description: Get current user permissions using standard OAuth2/OIDC flow with Logto token
      responses:
        '200':
          description: User permissions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user permissions retrieved successfully"
                  data:
                    type: object
                    properties:
                      user_roles:
                        type: array
                        items:
                          type: string
                        example: ["Admin"]
                      user_permissions:
                        type: array
                        items:
                          type: string
                        example: ["manage:systems", "read:systems"]
                      org_role:
                        type: string
                        example: "Owner"
                      org_permissions:
                        type: array
                        items:
                          type: string
                        example: ["manage:resellers", "create:customers"]
                      organization_id:
                        type: string
                        example: "org_123456789"
                      organization_name:
                        type: string
                        example: "ACME Corp"
        '401':
          $ref: '#/components/responses/Unauthorized'

  /user/profile:
    get:
      operationId: getUserProfile
      tags:
        - Backend - User
      summary: /user/profile - Get user profile (OAuth2/OIDC)
      description: Get current user profile using standard OAuth2/OIDC flow with Logto token
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "user profile retrieved successfully"
                  data:
                    $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ===========================================
  # COLLECT SERVICE ENDPOINTS
  # ===========================================

  /systems/info:
    get:
      operationId: getSystemInfo
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/info - Get system info
      description: Returns information about the authenticated system, including suspension and organization status.
      security:
        - BasicAuth: [system_key:system_secret]
      responses:
        '200':
          description: System info retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "system info retrieved successfully"
                  data:
                    type: object
                    properties:
                      system_id:
                        type: string
                        example: "abc-123"
                      system_key:
                        type: string
                        example: "my-system-key"
                      name:
                        type: string
                        example: "Milan Office Server"
                      type:
                        type: string
                        nullable: true
                        example: "ns8"
                      fqdn:
                        type: string
                        nullable: true
                        example: "server.example.com"
                      status:
                        type: string
                        example: "active"
                      suspended:
                        type: boolean
                        example: false
                      suspended_at:
                        type: string
                        format: date-time
                        nullable: true
                      deleted:
                        type: boolean
                        example: false
                      deleted_at:
                        type: string
                        format: date-time
                        nullable: true
                      registered:
                        type: boolean
                        example: true
                      registered_at:
                        type: string
                        format: date-time
                        nullable: true
                        example: "2025-01-15T10:00:00Z"
                      created_at:
                        type: string
                        format: date-time
                        example: "2025-01-10T08:00:00Z"
                      rebranding_enabled:
                        type: boolean
                        description: Whether rebranding is enabled for this system (directly or inherited through hierarchy)
                        example: false
                      organization:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Database UUID of the organization
                            example: "4405ffd0-0aca-44ef-bae2-c8545bce94f4"
                          logto_id:
                            type: string
                            description: Logto organization ID
                            example: "akkbs6x2wo82"
                          name:
                            type: string
                            description: Organization name
                            example: "Owner"
                          type:
                            type: string
                            description: Organization type in the hierarchy
                            enum: [owner, distributor, reseller, customer]
                            example: "owner"
                          suspended:
                            type: boolean
                            example: false
                          suspended_at:
                            type: string
                            format: date-time
                            nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: System not found or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /systems/inventory:
    post:
      operationId: collectSystemInventory
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/inventory - Collect system inventory
      description: System inventory collection endpoint with HTTP Basic authentication
      security:
        - BasicAuth: [system_key:system_secret]
      requestBody:
        required: true
        description: Raw inventory JSON from the system (structure varies by system type)
        content:
          application/json:
            schema:
              type: object
              description: Raw inventory data sent directly from the system
              additionalProperties: true
              example: {
                "$schema": "https://schema.nethserver.org/facts/2022-12.json",
                "uuid": "659d2fbe-792f-4a0d-ae58-f278304d4f7f",
                "installation": "nethserver",
                "facts": {
                  "cluster": {
                    "leader_node_id": "1",
                    "user_domains": [],
                    "subscription": "community",
                    "ui_name": "MyNethServer 8"
                  },
                  "nodes": {
                    "1": {
                      "cluster_leader": true,
                      "fqdn": "rl1.dp.nethserver.net",
                      "default_ipv4": "165.22.17.26",
                      "default_ipv6": "2a03:b0c0:3:f0:0:1:dbfe:3000",
                      "version": "3.17.0-dev.6",
                      "ui_name": "MyNodeRl1"
                    }
                  },
                  "modules": [
                    {
                      "id": "mail1",
                      "version": "1.7.4",
                      "name": "mail",
                      "node": "1",
                      "ui_name": "MyMail"
                    }
                  ]
                }
              }
      responses:
        '202':
          description: Inventory received and queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "Inventory received and queued for processing"
                  data:
                    type: object
                    properties:
                      data_size:
                        type: integer
                        description: Inventory data size in bytes
                        example: 10145
                      message:
                        type: string
                        description: A message from server
                        example: "Your inventory data has been received and will be processed shortly"
                      queue_status:
                        type: string
                        description: Queue status message
                        example: "queued"
                      system_key:
                        type: string
                        description: System KEY
                        example: "NETH-4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7"
                      timestamp:
                        type: string
                        format: date-time
                        description: Timestamp of received inventory
                        example: "2025-07-16T15:46:51.571831+02:00"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 413
                  message:
                    type: string
                    example: "Request too large"
                  data:
                    type: object
                    properties:
                      max_size_bytes:
                        type: integer
                        description: Maximum allowed request size in bytes
                        example: 10485760
                      received_bytes:
                        type: integer
                        description: Size of received request in bytes
                        example: 20971520
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: "Failed to process inventory"
                  data:
                    type: object
                    properties:
                      error:
                        type: string
                        example: "Processing queue unavailable"

  /systems/heartbeat:
    post:
      operationId: sendSystemHeartbeat
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/heartbeat - System heartbeat
      description: System heartbeat endpoint to track system liveness (every 10 minutes)
      security:
        - BasicAuth: [system_key:system_secret]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                system_key:
                  type: string
                  description: System KEY sending the heartbeat
                  example: "NETH-4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7"
              required:
                - system_key
      responses:
        '200':
          description: Heartbeat acknowledged
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "heartbeat acknowledged"
                  data:
                    type: object
                    properties:
                      system_key:
                        type: string
                        description: System KEY
                        example: "NETH-4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7"
                      acknowledged:
                        type: boolean
                        description: Whether heartbeat was acknowledged
                        example: true
                      last_heartbeat:
                        type: string
                        format: date-time
                        description: Timestamp of this heartbeat
                        example: "2025-07-21T10:25:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /systems/backups:
    post:
      operationId: uploadSystemBackup
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/backups - Upload a configuration backup
      description: |
        Stream a GPG-encrypted configuration snapshot to the backup store.
        The body is the ciphertext; SHA-256 is computed at ingest. The
        appliance authenticates with HTTP Basic auth using its
        `system_key:system_secret`.

        Server-side limits enforced before/during ingest:
        - Per-system rate limit (default 6/min, 60/hour) — `429 Retry-After` on hit
        - Per-system slot cap (default 10) — oldest pruned at retention
        - Per-system size cap (default 500 MiB total) — oldest pruned
        - Per-org aggregate quota (default 100 GiB) — `413` on hit
        - Per-upload size cap (default 2 GiB) — `413` on hit

        Object key shape: `{org_id}/{system_key}/{uuidv7}.{ext}`. The
        appliance never picks the destination prefix; it is server-derived
        from the authenticated identity.
      security:
        - BasicAuth: [system_key:system_secret]
      parameters:
        - name: X-Filename
          in: header
          required: false
          description: User-facing filename (sanitized server-side)
          schema:
            type: string
            example: "daily-backup-2026-04-12.tar.gz.gpg"
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Backup stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "backup stored"
                  data:
                    $ref: '#/components/schemas/BackupMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '429':
          description: Rate limit exceeded; retry after the time indicated by `Retry-After`.
        '503':
          description: Backup storage or org-quota service unavailable; retry later.
    get:
      operationId: listSystemBackupsAppliance
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/backups - List backups for the authenticated system
      description: |
        Returns metadata for every backup currently stored under the
        authenticated system's prefix. Cross-tenant access is impossible
        — the listing scope is server-derived from the credentials.
      security:
        - BasicAuth: [system_key:system_secret]
      responses:
        '200':
          description: Backups listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  data:
                    type: object
                    properties:
                      backups:
                        type: array
                        items:
                          $ref: '#/components/schemas/BackupMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: Backup storage unavailable.

  /systems/backups/{id}:
    get:
      operationId: downloadSystemBackupAppliance
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/backups/{id} - Download a backup
      description: |
        Stream the ciphertext body for a specific backup belonging to the
        authenticated system. Foreign IDs return `404`; the path can never
        escape the authenticated system's prefix.
      security:
        - BasicAuth: [system_key:system_secret]
      parameters:
        - name: id
          in: path
          required: true
          description: Backup ID (UUIDv7 plus extension)
          schema:
            type: string
            example: "01934fab-bc33-7890-a1b2-c3d4e5f6a7b8.tar.gz"
      responses:
        '200':
          description: Backup body streamed as `application/octet-stream`
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          description: Backup storage unavailable.
    delete:
      operationId: deleteSystemBackupAppliance
      servers:
        - url: https://collect.your-domain.com/api
          description: Collect API server (port 8081)
      tags:
        - Collect - Systems
      summary: /systems/backups/{id} - Delete a backup
      description: |
        Remove a specific backup belonging to the authenticated system.
        Foreign IDs return `404`.
      security:
        - BasicAuth: [system_key:system_secret]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Backup deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================================================
  # VALIDATORS
  # ===========================================================================
  /validators/vat/{entity_type}:
    get:
      operationId: validateVAT
      tags:
        - Backend - Validators
      summary: /validators/vat/{entity_type} - Validate VAT number
      description: Check if a VAT number exists in the specified entity type (distributors, resellers, customers)
      parameters:
        - name: entity_type
          in: path
          required: true
          description: Type of entity to check VAT against
          schema:
            type: string
            enum: [distributors, resellers, customers]
            example: "customers"
        - name: vat
          in: query
          required: true
          description: VAT number to validate
          schema:
            type: string
            example: "12345678901"
        - name: exclude_id
          in: query
          required: false
          description: Entity ID to exclude from check (useful for updates)
          schema:
            type: string
            example: "cust_123456789"
      responses:
        '200':
          description: VAT validation completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "VAT validation completed"
                  data:
                    $ref: '#/components/schemas/VATValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ===========================================
  # REBRANDING ENDPOINTS (Backend)
  # ===========================================

  /rebranding/products:
    get:
      operationId: getRebrandingProducts
      tags:
        - Backend - Rebranding
      summary: List rebrandable products
      description: Returns all products that support rebranding
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Rebrandable products retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      products:
                        type: array
                        items:
                          $ref: '#/components/schemas/RebrandableProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /rebranding/{org_id}/enable:
    patch:
      operationId: enableRebranding
      tags:
        - Backend - Rebranding
      summary: Enable rebranding for an organization
      description: Owner-only. Enables rebranding capability for a specific organization.
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
      responses:
        '200':
          description: Rebranding enabled
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'

  /rebranding/{org_id}/disable:
    patch:
      operationId: disableRebranding
      tags:
        - Backend - Rebranding
      summary: Disable rebranding for an organization
      description: Owner-only. Disables rebranding for a specific organization.
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
      responses:
        '200':
          description: Rebranding disabled
        '403':
          $ref: '#/components/responses/Forbidden'

  /rebranding/{org_id}/status:
    get:
      operationId: getRebrandingStatus
      tags:
        - Backend - Rebranding
      summary: Get rebranding status for an organization
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
      responses:
        '200':
          description: Rebranding status retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/RebrandingOrgStatus'
        '403':
          $ref: '#/components/responses/Forbidden'

  /rebranding/{org_id}/products:
    get:
      operationId: getRebrandingOrgProducts
      tags:
        - Backend - Rebranding
      summary: Get rebranding products for an organization
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
      responses:
        '200':
          description: Rebranding products retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/RebrandingOrgStatus'
        '403':
          $ref: '#/components/responses/Forbidden'

  /rebranding/{org_id}/products/{product_id}:
    put:
      operationId: uploadRebrandingAssets
      tags:
        - Backend - Rebranding
      summary: Upload rebranding assets for a product
      description: |
        Multipart upload of logos, favicon, background, and product name.
        All fields optional. Only provided fields are updated.
        Requires rebranding to be enabled for the organization.
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
        - name: product_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                product_name:
                  type: string
                  maxLength: 100
                logo_light_rect:
                  type: string
                  format: binary
                logo_dark_rect:
                  type: string
                  format: binary
                logo_light_square:
                  type: string
                  format: binary
                logo_dark_square:
                  type: string
                  format: binary
                favicon:
                  type: string
                  format: binary
                background_image:
                  type: string
                  format: binary
      responses:
        '200':
          description: Assets uploaded
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteRebrandingProduct
      tags:
        - Backend - Rebranding
      summary: Delete all rebranding assets for a product
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
        - name: product_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Product rebranding deleted
        '403':
          $ref: '#/components/responses/Forbidden'

  /rebranding/{org_id}/products/{product_id}/{asset}:
    get:
      operationId: getRebrandingAsset
      tags:
        - Backend - Rebranding
      summary: Get a rebranding asset binary
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
        - name: product_id
          in: path
          required: true
          schema:
            type: string
        - name: asset
          in: path
          required: true
          schema:
            type: string
            enum: [logo_light_rect, logo_dark_rect, logo_light_square, logo_dark_square, favicon, background_image]
      responses:
        '200':
          description: Asset binary
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRebrandingAsset
      tags:
        - Backend - Rebranding
      summary: Delete a single rebranding asset
      security:
        - BearerAuth: []
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
          description: Logto organization ID (logto_id, not the database UUID)
        - name: product_id
          in: path
          required: true
          schema:
            type: string
        - name: asset
          in: path
          required: true
          schema:
            type: string
            enum: [logo_light_rect, logo_dark_rect, logo_light_square, logo_dark_square, favicon, background_image]
      responses:
        '200':
          description: Asset deleted
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================
  # REBRANDING ENDPOINTS (Collect)
  # ===========================================

  /systems/rebranding:
    get:
      operationId: getSystemRebranding
      tags:
        - Collect - Rebranding
      summary: Get system rebranding configuration
      description: |
        Returns rebranding configuration for the authenticated system.
        Resolves hierarchy inheritance (customer -> reseller -> distributor).
        Response groups products by type (system vs application).
      security:
        - BasicAuth: []
      responses:
        '200':
          description: System rebranding configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/SystemRebrandingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /systems/rebranding/{product_id}/{asset}:
    get:
      operationId: getSystemRebrandingAsset
      tags:
        - Collect - Rebranding
      summary: Get a rebranding asset binary for the system
      description: Serves asset binary with hierarchy resolution
      security:
        - BasicAuth: []
      parameters:
        - name: product_id
          in: path
          required: true
          schema:
            type: string
        - name: asset
          in: path
          required: true
          schema:
            type: string
            enum: [logo_light_rect, logo_dark_rect, logo_light_square, logo_dark_square, favicon, background_image]
      responses:
        '200':
          description: Asset binary
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'

  # ===========================================
  # ALERTING ENDPOINTS (Backend - Totals & Trend)
  # ===========================================

  /services/mimir/alertmanager/api/v2/alerts:
    get:
      operationId: mimirAlertsGet
      tags:
        - Collect - Alerting
      summary: List active alerts
      description: |
        Lists all active alerts for the authenticated system, filtered by that system's `system_key`.
        
        Each system is scoped to see only its own alerts. The proxy automatically injects a `system_key` filter into the query.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
      security:
        - BasicAuth: []
      responses:
        '200':
          description: List of active alerts belonging to this system
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: mimirAlertsPost
      tags:
        - Collect - Alerting
      summary: Push alerts
      description: |
        Pushes one or more alerts to the Alertmanager for this system.
        
        The system's `system_key`, `system_id`, and `organization_id` are automatically injected and override any client-supplied values.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
        
        **Request body limits:** Maximum 10 MB per request (configurable via `API_MAX_REQUEST_SIZE`).
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Alerts accepted and forwarded to Alertmanager
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'

  /services/mimir/alertmanager/api/v2/silences:
    get:
      operationId: mimirSilencesGet
      tags:
        - Collect - Alerting
      summary: List silences
      description: |
        Lists all silences for this system's organization, filtered to silences that target this system's `system_key`.
        
        The proxy injects a `system_key` filter to ensure each system only sees its own silences.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
      security:
        - BasicAuth: []
      responses:
        '200':
          description: List of silences belonging to this system
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: mimirSilencesPost
      tags:
        - Collect - Alerting
      summary: Create or update a silence
      description: |
        Creates or updates a silence that targets this system's alerts.
        
        The proxy automatically injects a `system_key` matcher for this system into the silence, overwriting any client-supplied `system_key` matcher. This ensures silences can only target this system's alerts.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
        
        **Silence matchers:** The silence must include at least one matcher (e.g., `alertname`). The `system_key` matcher is added automatically and cannot be customized.
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Silence object with matchers, startsAt, endsAt, createdBy, comment
      responses:
        '200':
          description: Silence created or updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'

  /services/mimir/alertmanager/api/v2/silences/{silence_id}:
    parameters:
      - name: silence_id
        in: path
        required: true
        schema:
          type: string
        description: Silence UUID
    get:
      operationId: mimirSilenceGet
      tags:
        - Collect - Alerting
      summary: Get a silence
      description: |
        Returns a specific silence by ID, if it belongs to this system.
        
        Before forwarding the request to Alertmanager, the proxy verifies the silence contains an exact `system_key` matcher matching this system. If the silence does not belong to this system, a 403 Forbidden response is returned.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Silence details (only if it targets this system)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: mimirSilenceDelete
      tags:
        - Collect - Alerting
      summary: Delete a silence
      description: |
        Deletes a silence by ID, if it belongs to this system.
        
        Before forwarding the request to Alertmanager, the proxy verifies the silence contains an exact `system_key` matcher matching this system. If the silence does not belong to this system, a 403 Forbidden response is returned.
        
        **Access control:** Requires HTTP Basic Auth with valid system credentials.
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Silence deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '502':
          $ref: '#/components/responses/InternalServerError'

  # ===========================================
  # ALERTING ENDPOINTS (Collect - Alert History Webhook)
  # ===========================================

  /alert_history:
    post:
      operationId: receiveAlertHistory
      tags:
        - Collect - Alerting
      summary: Receive alert history webhook
      description: |
        Receives resolved alert webhooks from Alertmanager and persists them to the alert_history table.
        Firing alerts are ignored; only resolved alerts are stored.
        Authenticated via Bearer token (ALERTING_HISTORY_WEBHOOK_SECRET).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: "resolved"
                alerts:
                  type: array
                  items:
                    type: object
                receiver:
                  type: string
      responses:
        '204':
          description: Webhook processed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Webhook authentication not configured