{ "openapi": "3.0.0", "paths": { "/api/v1/federation/group-mappings/sync": { "post": { "description": "Runs a full reconciliation of federated memberships against the last-known Entra attributes stored in Keycloak, applying the currently-configured group mappings. Does NOT poll Entra (login remains authoritative for the cloud OIDC path). Returns aggregated counts. Requires Super Admin privileges.", "operationId": "triggerFederationSync", "parameters": [], "responses": { "200": { "description": "Reconciliation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationSyncResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Trigger federation reconciliation", "tags": [ "Federation Group Mappings" ] } }, "/api/v1/federation/group-mappings": { "get": { "description": "Lists federated group mappings across all organizations, optionally filtered by organization, provider, or enabled state. Requires Super Admin privileges.", "operationId": "listFederatedGroupMappings", "parameters": [ { "name": "organizationId", "required": false, "in": "query", "description": "Filter by organization", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "provider", "required": false, "in": "query", "description": "Filter by identity provider", "schema": { "example": "ENTRA", "type": "string", "enum": [ "ENTRA", "LDAP" ] } }, { "name": "enabled", "required": false, "in": "query", "description": "Filter by enabled state", "schema": { "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "Mappings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedGroupMappingListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List federated group mappings", "tags": [ "Federation Group Mappings" ] }, "post": { "description": "Creates a federated group mapping tying a provider app-role / group to a WFM role within an organization. Requires Super Admin privileges.", "operationId": "createFederatedGroupMapping", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFederatedGroupMappingDto" } } } }, "responses": { "201": { "description": "Mapping created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedGroupMappingResponseDto" } } } }, "400": { "description": "Invalid input data or role does not exist" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" }, "409": { "description": "Mapping already exists for this provider/externalId" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create federated group mapping", "tags": [ "Federation Group Mappings" ] } }, "/api/v1/federation/group-mappings/{id}": { "get": { "description": "Retrieves a single federated group mapping. Requires Super Admin privileges.", "operationId": "getFederatedGroupMapping", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Mapping UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Mapping retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedGroupMappingResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Mapping not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get federated group mapping", "tags": [ "Federation Group Mappings" ] }, "patch": { "description": "Updates a federated group mapping. Requires Super Admin privileges.", "operationId": "updateFederatedGroupMapping", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Mapping UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFederatedGroupMappingDto" } } } }, "responses": { "200": { "description": "Mapping updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedGroupMappingResponseDto" } } } }, "400": { "description": "Invalid input data or role does not exist" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Mapping not found" }, "409": { "description": "Mapping already exists for this provider/externalId" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update federated group mapping", "tags": [ "Federation Group Mappings" ] }, "delete": { "description": "Disables (soft-removes) a federated group mapping so it is no longer resolved at login time, while preserving provenance for existing federated memberships. Requires Super Admin privileges.", "operationId": "deleteFederatedGroupMapping", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Mapping UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Mapping disabled successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Mapping not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable federated group mapping", "tags": [ "Federation Group Mappings" ] } }, "/api/v1/devices": { "get": { "description": "Retrieves a paginated list of devices with optional filtering by status and labels.", "operationId": "listDevices", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of devices to return", "schema": { "minimum": 1, "maximum": 1000, "default": 20, "example": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of devices to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for cursor-based pagination (alternative to offset)", "schema": { "example": "eyJpZCI6IjEyMzQifQ==", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by device status", "schema": { "example": "ONLINE", "type": "string", "enum": [ "ONLINE", "OFFLINE", "PENDING", "ERROR" ] } }, { "name": "labels", "required": false, "in": "query", "description": "Filter by device labels (JSON object)", "schema": { "additionalProperties": { "type": "string" }, "example": { "environment": "production", "region": "us-west" }, "type": "object" } }, { "name": "search", "required": false, "in": "query", "description": "Free-text search — matches device name, clientId, and Margo self-reported device ID (case-insensitive substring)", "schema": { "example": "edge-01", "type": "string" } }, { "name": "architecture", "required": false, "in": "query", "description": "Filter by CPU architecture as reported in capabilities.cpu.architecture", "schema": { "example": "arm64", "type": "string", "enum": [ "amd64", "arm64", "arm" ] } }, { "name": "appVersion", "required": false, "in": "query", "description": "Filter devices that have at least one non-removed deployment of a specific application version", "schema": { "example": "1.2.3", "type": "string" } } ], "responses": { "200": { "description": "List of devices retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List devices", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}": { "get": { "description": "Retrieves detailed information about a specific device.", "operationId": "getDevice", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "Device retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get device by ID", "tags": [ "Devices" ] }, "patch": { "description": "Updates device properties such as name and labels.", "operationId": "updateDevice", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeviceDto" } } } }, "responses": { "200": { "description": "Device updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update device", "tags": [ "Devices" ] }, "delete": { "description": "Soft deletes a device. The device can be restored if needed.", "operationId": "deleteDevice", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "204": { "description": "Device deleted successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete device", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/activity": { "get": { "description": "Retrieves recent activity events for a specific device, including deployment status changes and certificate events.", "operationId": "getDeviceActivity", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of activity items to return", "schema": { "default": 20, "type": "number" } } ], "responses": { "200": { "description": "Device activity retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentActivityResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get device activity log", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/release-reported-device-id": { "post": { "description": "FM-1043: clears this device’s reportedDeviceId (the Margo self-reported DeviceId from its capabilities manifest) without soft-deleting the device. Recovery action for an ID-squatting collision — use when the rejection-audit trail shows this device is holding a DeviceId that belongs to another device, so the true owner’s next capabilities report can claim it.", "operationId": "releaseReportedDeviceId", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "reportedDeviceId claim released successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Release a reportedDeviceId claim", "tags": [ "Devices" ] } }, "/api/v1/devices/{deviceId}/certificates": { "get": { "description": "Retrieves all certificates for a specific device.", "operationId": "listDeviceCertificates", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "List of device certificates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCertificateListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List device certificates", "tags": [ "Device Certificates" ] } }, "/api/v1/devices/{deviceId}/certificates/{certificateId}": { "get": { "description": "Retrieves detailed information about a specific device certificate.", "operationId": "getDeviceCertificate", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "certificateId", "required": true, "in": "path", "description": "Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } } ], "responses": { "200": { "description": "Device certificate retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCertificateResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Device or certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get device certificate", "tags": [ "Device Certificates" ] } }, "/api/v1/devices/{deviceId}/certificates/{certificateId}/revoke": { "post": { "description": "Revokes a device certificate. This action cannot be undone.", "operationId": "revokeDeviceCertificate", "parameters": [ { "name": "x-user-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "deviceId", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "certificateId", "required": true, "in": "path", "description": "Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeCertificateDto" } } } }, "responses": { "200": { "description": "Certificate revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Invalid revocation reason" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (operator or admin)" }, "404": { "description": "Device or certificate not found, or certificate already revoked" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Revoke device certificate", "tags": [ "Device Certificates" ] } }, "/api/v1/devices/{deviceId}/certificates/{certificateId}/renew": { "post": { "description": "Extends the expiry of a device certificate. WFM-internal bookkeeping only; does not require the device to re-onboard.", "operationId": "renewDeviceCertificate", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "certificateId", "required": true, "in": "path", "description": "Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewCertificateDto" } } } }, "responses": { "200": { "description": "Certificate renewed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Cannot renew a revoked certificate" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (operator or admin)" }, "404": { "description": "Device or certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Renew device certificate", "tags": [ "Device Certificates" ] } }, "/api/v1/groups/stats": { "get": { "description": "Retrieves fleet-wide statistics including device counts and available label keys.", "operationId": "getFleetStats", "parameters": [], "responses": { "200": { "description": "Fleet statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetStatsResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get fleet statistics", "tags": [ "Groups" ] } }, "/api/v1/groups/labels": { "get": { "description": "Retrieves all unique label keys used in the organization.", "operationId": "getLabelKeys", "parameters": [], "responses": { "200": { "description": "Label keys retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelKeysResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get label keys", "tags": [ "Groups" ] }, "patch": { "description": "Bulk updates labels on devices matching a selector.", "operationId": "bulkUpdateLabels", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateLabelsDto" } } } }, "responses": { "200": { "description": "Labels updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperationResponseDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Bulk update labels", "tags": [ "Groups" ] } }, "/api/v1/groups/labels/{key}/values": { "get": { "description": "Retrieves all unique values for a specific label key.", "operationId": "getLabelValues", "parameters": [ { "name": "key", "required": true, "in": "path", "description": "Label key", "schema": { "example": "environment", "type": "string" } } ], "responses": { "200": { "description": "Label values retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelValuesResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get label values", "tags": [ "Groups" ] } }, "/api/v1/groups/by-label/{key}": { "get": { "description": "Retrieves device statistics grouped by a specific label key.", "operationId": "getStatsByLabel", "parameters": [ { "name": "key", "required": true, "in": "path", "description": "Label key to group by", "schema": { "example": "environment", "type": "string" } } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupStatsByLabelResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get statistics by label", "tags": [ "Groups" ] } }, "/api/v1/groups/query": { "post": { "description": "Retrieves statistics for devices matching a label selector.", "operationId": "queryGroupStats", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labelSelector": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "production", "region": "us-west" } } }, "required": [ "labelSelector" ] } } } }, "responses": { "200": { "description": "Group statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupStatsResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Query group statistics", "tags": [ "Groups" ] }, "get": { "description": "Retrieves statistics for devices matching label query parameters. Pass label key-value pairs as query parameters (e.g., ?env=prod®ion=us-east). Reserved keys `limit` and `offset` are excluded from label matching.", "operationId": "getGroupStats", "parameters": [], "responses": { "200": { "description": "Group statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupStatsResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get group statistics via query params", "tags": [ "Groups" ] } }, "/api/v1/groups/labels/add": { "post": { "description": "Adds a label to all devices matching a selector.", "operationId": "addLabelToGroup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLabelToGroupDto" } } } }, "responses": { "200": { "description": "Label added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperationResponseDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Add label to group", "tags": [ "Groups" ] } }, "/api/v1/groups/labels/remove": { "post": { "description": "Removes a label from all devices matching a selector.", "operationId": "removeLabelFromGroup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveLabelFromGroupDto" } } } }, "responses": { "200": { "description": "Label removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperationResponseDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Remove label from group", "tags": [ "Groups" ] } }, "/api/v1/groups/devices": { "delete": { "description": "Soft deletes devices matching a selector.", "operationId": "bulkDeleteGroup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteGroupDto" } } } }, "responses": { "200": { "description": "Devices deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteResponseDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Bulk delete devices", "tags": [ "Groups" ] } }, "/api/v1/organizations": { "post": { "description": "Creates a new organization. Requires Super Admin privileges.", "operationId": "createOrganization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationDto" } } } }, "responses": { "201": { "description": "Organization created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "409": { "description": "Organization with this slug already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create organization", "tags": [ "Organizations" ] }, "get": { "description": "Retrieves a list of all organizations. Requires Super Admin privileges.", "operationId": "listOrganizations", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term for organization name or slug", "schema": { "example": "acme", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Filter by exact organization name", "schema": { "example": "Acme Corporation", "type": "string" } }, { "name": "active", "required": false, "in": "query", "description": "Filter by active status (deprecated, use status filter)", "deprecated": true, "schema": { "example": true, "type": "boolean" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by organization status", "schema": { "example": "active", "type": "string", "enum": [ "active", "suspended", "pending", "disabled" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "Organizations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List organizations", "tags": [ "Organizations" ] } }, "/api/v1/organizations/stats": { "get": { "description": "Returns total organization count and counts by status. Requires Super Admin privileges.", "operationId": "getOrganizationAggregateStats", "parameters": [], "responses": { "200": { "description": "Aggregate stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationAggregateStatsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get aggregate organization stats", "tags": [ "Organizations" ] } }, "/api/v1/organizations/empty": { "get": { "description": "Returns organizations with zero members. The organization the caller is currently operating in (active tenant) is never included, so it can never be purged. Requires Super Admin privileges.", "operationId": "getEmptyOrganizations", "parameters": [], "responses": { "200": { "description": "Empty organizations retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get empty organizations", "tags": [ "Organizations" ] } }, "/api/v1/organizations/bulk": { "delete": { "description": "Purges multiple organizations, cascading through each org's devices, deployments and applications (soft-deleted) before removing the org itself. The organization the caller is currently operating in (active tenant) is never deleted — it is dropped from the request and reported in the `errors` array as skipped. The response reports how many organizations were purged, the aggregated cascade counts, and a per-organization error for any that could not be removed. Requires Super Admin privileges.", "operationId": "bulkDeleteOrganizations", "parameters": [], "responses": { "200": { "description": "Bulk delete completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteOrganizationsResultDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Bulk delete organizations", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}": { "get": { "description": "Retrieves an organization by its unique identifier.", "operationId": "getOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Organization retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization by ID", "tags": [ "Organizations" ] }, "patch": { "description": "Updates an existing organization. Requires Super Admin privileges.", "operationId": "updateOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationDto" } } } }, "responses": { "200": { "description": "Organization updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update organization", "tags": [ "Organizations" ] }, "delete": { "description": "Deletes an organization. When `force=true`, performs cascading deletion of all users, devices, deployments, and applications. Multi-tenant users keep their account and lose membership in this org only; single-tenant users are hard-deleted. Requires Super Admin privileges.", "operationId": "deleteOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "force", "required": false, "in": "query", "description": "When set to `true`, performs cascading deletion across users, devices, deployments, and applications. Optional.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization force-deleted with cascade summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForceDeleteResultDto" } } } }, "204": { "description": "Organization deleted successfully (no force)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" }, "409": { "description": "Organization has active resources or is your own" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete organization", "tags": [ "Organizations" ] } }, "/api/v1/organizations/by-slug/{slug}": { "get": { "description": "Retrieves an organization by its URL-friendly slug.", "operationId": "getOrganizationBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Organization slug", "schema": { "example": "acme-corp", "type": "string" } } ], "responses": { "200": { "description": "Organization retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization by slug", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/stats": { "get": { "description": "Retrieves an organization with its statistics (user count, device count, etc.).", "operationId": "getOrganizationWithStats", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Organization with stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWithStatsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization with stats", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/enable": { "post": { "description": "Enables a disabled organization. Requires Super Admin privileges.", "operationId": "enableOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableOrganizationDto" } } } }, "responses": { "200": { "description": "Organization enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Organization is already enabled" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Enable organization", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/disable": { "post": { "description": "Disables an active organization. Requires Super Admin privileges.", "operationId": "disableOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableOrganizationDto" } } } }, "responses": { "200": { "description": "Organization disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Organization is already disabled" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable organization", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/suspend": { "post": { "description": "Temporarily suspends an organization. Different from disable - intended for reversible suspension. Requires Super Admin privileges.", "operationId": "suspendOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendOrganizationDto" } } } }, "responses": { "200": { "description": "Organization suspended successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Organization is already suspended or disabled" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Suspend organization", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/rename": { "post": { "description": "Renames an organization with new name and optional slug. Requires Super Admin privileges.", "operationId": "renameOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameOrganizationDto" } } } }, "responses": { "200": { "description": "Organization renamed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" }, "409": { "description": "Slug already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Rename organization", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/deletion-check": { "get": { "description": "Returns blockers preventing deletion. Requires Super Admin privileges.", "operationId": "checkOrganizationDeletion", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deletion check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionCheckResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Check if organization can be deleted", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/bulk-users": { "post": { "description": "Perform bulk operations on users within an organization. Requires Super Admin privileges.", "operationId": "organizationBulkUserOperation", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBulkOperationDto" } } } }, "responses": { "200": { "description": "Bulk operation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBulkOperationResultDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Bulk user operations", "tags": [ "Organizations" ] } }, "/api/v1/organizations/{id}/users/{userId}/reset-password": { "post": { "description": "Triggers a password reset for a user that is a member of this organization. Allowed for tenant admins (USERS_WRITE) and superadmins. Refuses self-reset (use the profile security page instead) and reset for inactive users.\n\n`delivery: 'email'` (the default) is NON-DESTRUCTIVE: the existing password keeps working and the user receives a Keycloak `UPDATE_PASSWORD` email carrying the reset form — only the user sets the new password. Delivery preconditions are checked before anything is mutated, so a `409 no-delivery-channel` means nothing was changed.\n\n`delivery: 'display'` is the documented no-SMTP / air-gap recovery path only: it rotates the credential and returns `temporaryPassword` exactly once.", "operationId": "resetUserPasswordInOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordDto" } } } }, "responses": { "200": { "description": "Password reset triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetResponseDto" } } } }, "400": { "description": "Self-reset attempted or user is not active" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks USERS_WRITE in this org" }, "404": { "description": "User is not a member of this organization" }, "409": { "description": "no-delivery-channel — delivery='email' was requested but the user has no linked Keycloak account or the realm has no SMTP server. Nothing was changed." } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Reset password for a user in this organization", "tags": [ "Organizations" ] } }, "/api/v1/users": { "post": { "description": "Creates a new user. Requires Super Admin privileges.", "operationId": "createUser", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserDto" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "409": { "description": "User with this email already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create user", "tags": [ "Users" ] }, "get": { "description": "Retrieves a list of all users. Requires Super Admin privileges.", "operationId": "listUsers", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term for user name or email", "schema": { "example": "john", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by exact email address", "schema": { "format": "email", "example": "john.doe@example.com", "type": "string" } }, { "name": "active", "required": false, "in": "query", "description": "Filter by active status", "schema": { "example": true, "type": "boolean" } }, { "name": "isSuperAdmin", "required": false, "in": "query", "description": "Filter by super admin status", "schema": { "example": false, "type": "boolean" } }, { "name": "include", "required": false, "in": "query", "description": "Include related data. Use \"organizations\" to include organization memberships.", "schema": { "example": "organizations", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List users", "tags": [ "Users" ] } }, "/api/v1/users/stats": { "get": { "description": "Returns platform-wide user stats: total, byStatus (active/inactive), byRole keyed by role name, and pendingInvitations. Requires Super Admin privileges.", "operationId": "getUserStats", "parameters": [], "responses": { "200": { "description": "User stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAggregateStatsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get aggregate user stats", "tags": [ "Users" ] } }, "/api/v1/users/{id}": { "get": { "description": "Retrieves a user with their organization memberships. Requires Super Admin privileges.", "operationId": "getUser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "User retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWithOrganizationsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get user by ID", "tags": [ "Users" ] }, "put": { "description": "Updates an existing user. Requires Super Admin privileges.", "operationId": "updateUser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserDto" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update user", "tags": [ "Users" ] }, "delete": { "description": "Deletes a user. Requires Super Admin privileges.", "operationId": "deleteUser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "User deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete user", "tags": [ "Users" ] } }, "/api/v1/users/{id}/organizations": { "post": { "description": "Adds a user to an organization with a specific role. Requires Super Admin privileges.", "operationId": "addUserToOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToOrganizationDto" } } } }, "responses": { "204": { "description": "User added to organization successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User or organization not found" }, "409": { "description": "User already belongs to this organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Add user to organization", "tags": [ "Users" ] } }, "/api/v1/users/{id}/organizations/{organizationId}": { "delete": { "description": "Removes a user from an organization. Requires Super Admin privileges.", "operationId": "removeUserFromOrganization", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "User removed from organization successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User or organization membership not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Remove user from organization", "tags": [ "Users" ] } }, "/api/v1/users/{id}/resend-verification": { "post": { "description": "Asks Keycloak to re-send the verification e-mail for a user whose address is not yet verified. Returns 400 when the address is already verified, because sending would imply the account is blocked when it is not.", "operationId": "resendUserVerificationEmail", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationResponseDto" } } } }, "400": { "description": "The address is already verified" }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found, or has no Keycloak account" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Resend the e-mail verification message", "tags": [ "Users" ] } }, "/api/v1/users/{id}/keycloak-link": { "delete": { "description": "Unbinds users.keycloakId so the account can be re-linked on next sign-in, subject to the FM-837 checks. Use when a Keycloak account was legitimately re-created. Memberships and system roles are preserved. Requires Super Admin privileges.", "operationId": "clearUserKeycloakLink", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Link cleared" }, "400": { "description": "The user has no Keycloak link to clear" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Clear the link between a user and their Keycloak identity", "tags": [ "Users" ] } }, "/api/v1/users/{id}/organizations/{organizationId}/role": { "put": { "description": "Updates a user's role in an organization. Requires USERS_WRITE or ORG_WRITE permission. Cannot change own role or escalate beyond own role level.", "operationId": "updateUserOrganizationRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRoleDto" } } } }, "responses": { "204": { "description": "User role updated successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Cannot change own role or escalate privileges" }, "404": { "description": "User, organization, or role not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update user role in organization", "tags": [ "Users" ] } }, "/api/v1/users/{id}/enable": { "post": { "description": "Enables a disabled user account. Requires Super Admin privileges.", "operationId": "enableUser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableUserDto" } } } }, "responses": { "200": { "description": "User enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "400": { "description": "User is already enabled" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Enable user", "tags": [ "Users" ] } }, "/api/v1/users/{id}/disable": { "post": { "description": "Disables a user account. Requires Super Admin privileges. Cannot disable yourself or other superusers unless you are a superuser.", "operationId": "disableUser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableUserDto" } } } }, "responses": { "200": { "description": "User disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "400": { "description": "User is already disabled" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Cannot disable yourself or superusers" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable user", "tags": [ "Users" ] } }, "/api/v1/users/{id}/reset-password": { "post": { "description": "Triggers a password reset for a user. Requires Super Admin privileges.\n\n`delivery: 'email'` (the default) is NON-DESTRUCTIVE: the user's existing password keeps working, Keycloak records an `UPDATE_PASSWORD` required action and emails them the reset form. Only the user can set the new password. Every delivery precondition is checked before anything is mutated, so a `409 no-delivery-channel` means nothing was changed.\n\n`delivery: 'display'` is the documented no-SMTP / air-gap recovery path only. It rotates the credential to a generated value, marks it temporary in Keycloak and returns it in `temporaryPassword` exactly once — it cannot be retrieved again.", "operationId": "resetUserPassword", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordDto" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" }, "409": { "description": "no-delivery-channel — delivery='email' was requested but the user has no linked Keycloak account or the realm has no SMTP server. Nothing was changed." } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Reset user password", "tags": [ "Users" ] } }, "/api/v1/users/{id}/grant-superuser": { "post": { "description": "Grants superuser (system admin) role to a user. Requires Super Admin privileges.", "operationId": "grantSuperuser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Superuser role granted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Grant superuser role", "tags": [ "Users" ] } }, "/api/v1/users/{id}/revoke-superuser": { "post": { "description": "Revokes superuser (system admin) role from a user. Requires Super Admin privileges.", "operationId": "revokeSuperuser", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Superuser role revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } }, "400": { "description": "User does not have superuser role" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Revoke superuser role", "tags": [ "Users" ] } }, "/api/v1/users/bulk": { "post": { "description": "Performs a bulk operation on multiple users. Supported actions: enable, disable, delete, reset_password, assign_role. Requires Super Admin privileges.", "operationId": "bulkUserOperation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperationDto" } } } }, "responses": { "200": { "description": "Bulk operation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperationResultDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Bulk user operation", "tags": [ "Users" ] } }, "/api/v1/users/export": { "post": { "description": "Exports users to CSV or JSON format. Requires Super Admin privileges.", "operationId": "exportUsers", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportUsersDto" } } } }, "responses": { "200": { "description": "Users exported successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Export users", "tags": [ "Users" ] } }, "/api/v1/organizations/{orgId}/members/stats": { "get": { "description": "Returns aggregate stats for members of the organization: total, byStatus (active/inactive), byRole keyed by role name, and pendingInvitations.", "operationId": "getOrganizationMemberStats", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAggregateStatsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization member stats", "tags": [ "Organization Members" ] } }, "/api/v1/organizations/{orgId}/members": { "get": { "description": "Retrieves a list of members in the organization.", "operationId": "listOrganizationMembers", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search term for user name or email", "schema": { "example": "john", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by exact email address", "schema": { "format": "email", "example": "john.doe@example.com", "type": "string" } }, { "name": "active", "required": false, "in": "query", "description": "Filter by active status", "schema": { "example": true, "type": "boolean" } }, { "name": "isSuperAdmin", "required": false, "in": "query", "description": "Filter by super admin status", "schema": { "example": false, "type": "boolean" } }, { "name": "include", "required": false, "in": "query", "description": "Include related data. Use \"organizations\" to include organization memberships.", "schema": { "example": "organizations", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "Members retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List organization members", "tags": [ "Organization Members" ] } }, "/api/v1/organizations/{orgId}/members/{userId}": { "get": { "description": "Retrieves details of a specific organization member.", "operationId": "getOrganizationMember", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Member retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWithOrganizationsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Member not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization member", "tags": [ "Organization Members" ] }, "delete": { "description": "Removes a member from the organization.", "operationId": "removeOrganizationMember", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Member removed successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Member not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Remove member from organization", "tags": [ "Organization Members" ] } }, "/api/v1/organizations/{orgId}/members/{userId}/role": { "put": { "description": "Updates a member's role in the organization.", "operationId": "updateOrganizationMemberRole", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRoleDto" } } } }, "responses": { "204": { "description": "Member role updated successfully" }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Member or role not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update member role", "tags": [ "Organization Members" ] } }, "/api/v1/tenant/members/stats": { "get": { "description": "Returns aggregate stats for members of the active organization (resolved from URL slug / active switch): total, byStatus (active/inactive), byRole keyed by role name, and pendingInvitations.", "operationId": "getTenantMemberStats", "parameters": [], "responses": { "200": { "description": "Stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAggregateStatsDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get active-tenant member stats", "tags": [ "Tenant Members" ] } }, "/api/v1/tenant/members": { "get": { "description": "Retrieves a list of members in the active organization (resolved from URL slug / active switch).", "operationId": "listTenantMembers", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term for user name or email", "schema": { "example": "john", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by exact email address", "schema": { "format": "email", "example": "john.doe@example.com", "type": "string" } }, { "name": "active", "required": false, "in": "query", "description": "Filter by active status", "schema": { "example": true, "type": "boolean" } }, { "name": "isSuperAdmin", "required": false, "in": "query", "description": "Filter by super admin status", "schema": { "example": false, "type": "boolean" } }, { "name": "include", "required": false, "in": "query", "description": "Include related data. Use \"organizations\" to include organization memberships.", "schema": { "example": "organizations", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "Members retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List active-tenant members", "tags": [ "Tenant Members" ] } }, "/api/v1/me/profile": { "get": { "operationId": "UserProfileController_getMyProfile", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get current user profile", "tags": [ "Profile" ] }, "put": { "operationId": "UserProfileController_updateMyProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update current user profile", "tags": [ "Profile" ] } }, "/api/v1/me/profile/notifications": { "put": { "operationId": "UserProfileController_updateNotificationPreferences", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationPreferencesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update notification preferences", "tags": [ "Profile" ] } }, "/api/v1/me/password": { "post": { "operationId": "UserProfileController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordDto" } } } }, "responses": { "204": { "description": "Password changed successfully" }, "400": { "description": "Invalid current password or weak new password" }, "409": { "description": "FM-864: the account is not linked to an identity provider account, so it has no password to change" }, "502": { "description": "FM-864: the identity provider rejected the new password; nothing was changed" }, "503": { "description": "FM-864: the identity provider is unavailable, so the password was not changed" } }, "security": [ { "bearer": [] } ], "summary": "Change password", "tags": [ "Profile" ] } }, "/api/v1/me/sessions": { "get": { "operationId": "UserProfileController_getMySessions", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List active sessions", "tags": [ "Profile" ] }, "delete": { "operationId": "UserProfileController_terminateAllOtherSessions", "parameters": [], "responses": { "200": { "description": "Number of sessions terminated" } }, "security": [ { "bearer": [] } ], "summary": "Terminate all other sessions", "tags": [ "Profile" ] } }, "/api/v1/me/sessions/{sessionId}": { "delete": { "operationId": "UserProfileController_terminateSession", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session terminated" }, "400": { "description": "Cannot terminate current session" }, "404": { "description": "Session not found" } }, "security": [ { "bearer": [] } ], "summary": "Terminate a session", "tags": [ "Profile" ] } }, "/api/v1/me/activity": { "get": { "operationId": "UserProfileController_getMyActivity", "parameters": [ { "name": "activityTypes", "required": false, "in": "query", "description": "Filter by activity types", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination", "schema": { "default": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get my activity history", "tags": [ "Profile" ] } }, "/api/v1/organizations/{orgId}/api-keys": { "post": { "description": "Creates a new API key for programmatic access. The full key is only returned once on creation.", "operationId": "createApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyDto" } } } }, "responses": { "201": { "description": "API key created successfully. Store the key securely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions\n\nForbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create API key", "tags": [ "API Keys" ] }, "get": { "description": "Retrieves all API keys for the organization with pagination.", "operationId": "listApiKeys", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search by API key name", "schema": { "example": "production", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } } ], "responses": { "200": { "description": "API keys retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List API keys", "tags": [ "API Keys" ] } }, "/api/v1/organizations/{orgId}/api-keys/{id}": { "get": { "description": "Retrieves a specific API key by its unique identifier.", "operationId": "getApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "API Key UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "API key retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "API key not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get API key by ID", "tags": [ "API Keys" ] }, "put": { "description": "Updates an existing API key name, description, or permissions.", "operationId": "updateApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "API Key UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyDto" } } } }, "responses": { "200": { "description": "API key updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "API key not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update API key", "tags": [ "API Keys" ] }, "delete": { "description": "Revokes an API key, immediately invalidating it for all future requests.", "operationId": "revokeApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "API Key UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "API key revoked successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "API key not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Revoke API key", "tags": [ "API Keys" ] } }, "/api/v1/organizations/{orgId}/invitations": { "post": { "description": "Sends an invitation email to a user to join the organization.", "operationId": "createInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationDto" } } } }, "responses": { "201": { "description": "Invitation created and email sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "409": { "description": "User already in organization or invitation pending" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create invitation", "tags": [ "Invitations" ] }, "get": { "description": "Retrieves all invitations for the organization.", "operationId": "listInvitations", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by email address", "schema": { "format": "email", "example": "user@example.com", "type": "string" } }, { "name": "pending", "required": false, "in": "query", "description": "Filter for pending invitations only", "schema": { "example": true, "type": "boolean" } }, { "name": "expired", "required": false, "in": "query", "description": "Filter for expired invitations only", "schema": { "example": false, "type": "boolean" } } ], "responses": { "200": { "description": "Invitations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List invitations", "tags": [ "Invitations" ] } }, "/api/v1/organizations/{orgId}/invitations/{id}": { "get": { "description": "Retrieves a specific invitation by its unique identifier.", "operationId": "getInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Invitation UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Invitation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Invitation not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get invitation by ID", "tags": [ "Invitations" ] }, "delete": { "description": "Deletes an invitation, preventing it from being accepted.", "operationId": "deleteInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Invitation UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Invitation deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Invitation not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete invitation", "tags": [ "Invitations" ] } }, "/api/v1/organizations/{orgId}/invitations/{id}/resend": { "post": { "description": "Resends an invitation email and optionally resets the expiration.", "operationId": "resendInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Invitation UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendInvitationDto" } } } }, "responses": { "200": { "description": "Invitation resent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponseDto" } } } }, "400": { "description": "Invitation already accepted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Invitation not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Resend invitation", "tags": [ "Invitations" ] } }, "/api/v1/invitations/{token}": { "get": { "description": "Retrieves invitation details using the token from the invitation email. No authentication required.", "operationId": "getInvitationByToken", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Invitation token from the email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationDetailsDto" } } } }, "400": { "description": "Invalid or expired token" }, "404": { "description": "Invitation not found" } }, "summary": "Get invitation details by token", "tags": [ "Public Invitations" ] } }, "/api/v1/invitations/accept": { "post": { "description": "Accepts an invitation and adds the user to the organization. If the user does not exist, name and password are required.", "operationId": "acceptInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationDto" } } } }, "responses": { "204": { "description": "Invitation accepted successfully" }, "400": { "description": "Invalid token, expired invitation, or missing required fields" }, "404": { "description": "Invitation not found" }, "409": { "description": "Invitation already accepted" } }, "summary": "Accept invitation", "tags": [ "Public Invitations" ] } }, "/api/v1/organizations/{orgId}/roles/permissions": { "get": { "description": "Retrieves all available permissions for role creation.", "operationId": "listPermissions", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Permissions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List available permissions", "tags": [ "Roles" ] } }, "/api/v1/organizations/{orgId}/roles": { "get": { "description": "Retrieves all roles available in the organization (system + custom roles).", "operationId": "listRoles", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term for role name", "schema": { "example": "admin", "type": "string" } }, { "name": "includeSystem", "required": false, "in": "query", "description": "Whether to include system-defined roles", "schema": { "default": true, "example": true, "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip for pagination", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List roles", "tags": [ "Roles" ] }, "post": { "description": "Creates a new custom role for the organization.", "operationId": "createRole", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleDto" } } } }, "responses": { "201": { "description": "Role created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "409": { "description": "Role with this name already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create custom role", "tags": [ "Roles" ] } }, "/api/v1/organizations/{orgId}/roles/{id}": { "get": { "description": "Retrieves a specific role by its unique identifier.", "operationId": "getRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Role UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Role retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Role not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get role by ID", "tags": [ "Roles" ] }, "patch": { "description": "Updates an existing custom role. System roles cannot be modified.", "operationId": "updateRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Role UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleDto" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponseDto" } } } }, "400": { "description": "Invalid input data or cannot modify system role" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Role not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update custom role", "tags": [ "Roles" ] }, "delete": { "description": "Deletes a custom role. System roles cannot be deleted.", "operationId": "deleteRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Role UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Role deleted successfully" }, "400": { "description": "Cannot delete system role or role in use" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Role not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete custom role", "tags": [ "Roles" ] } }, "/api/v1/audit": { "get": { "description": "Searches audit logs with filters and pagination.", "operationId": "searchAuditLogs", "parameters": [ { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "apiKeyId", "required": false, "in": "query", "description": "Filter by API key ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Filter by audit action type(s)", "schema": { "example": [ "CREATE", "UPDATE" ], "type": "array", "items": { "type": "string", "enum": [ "CREATE", "READ", "UPDATE", "DELETE", "LOGIN", "LOGOUT", "LOGIN_FAILED", "PERMISSION_GRANTED", "PERMISSION_DENIED", "EXPORT", "IMPORT", "BULK_UPDATE", "BULK_DELETE", "PASSWORD_CHANGE", "API_KEY_CREATED", "API_KEY_REVOKED", "CERTIFICATE_ISSUED", "CERTIFICATE_REVOKED", "DEPLOYMENT_STARTED", "DEPLOYMENT_COMPLETED", "DEPLOYMENT_FAILED", "DEPLOYMENT_ROLLED_BACK", "DEVICE_ONBOARDING_REJECTED", "DEVICE_CAPABILITY_REPORT_REJECTED", "DEVICE_STATUS_REPORT_REJECTED", "DEVICE_DESIRED_STATE_FETCH_REJECTED", "DEVICE_ONBOARDING_REJECTED_SUMMARY" ] } } }, { "name": "entityType", "required": false, "in": "query", "description": "Filter by entity type(s)", "schema": { "example": [ "Device", "User" ], "type": "array", "items": { "type": "string" } } }, { "name": "entityId", "required": false, "in": "query", "description": "Filter by specific entity ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002", "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "example": true, "type": "boolean" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter logs from this date", "schema": { "format": "date-time", "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter logs until this date", "schema": { "format": "date-time", "example": "2024-12-31T23:59:59Z", "type": "string" } }, { "name": "ipAddress", "required": false, "in": "query", "description": "Filter by IP address", "schema": { "example": "192.168.1.100", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Full-text search in entity name and error message", "schema": { "example": "device-001", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for cursor-based pagination", "schema": { "example": "eyJpZCI6IjEyMzQifQ==", "type": "string" } } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Search audit logs", "tags": [ "Audit" ] } }, "/api/v1/audit/stats": { "get": { "description": "Retrieves audit log statistics for the organization.", "operationId": "getAuditStats", "parameters": [ { "name": "startDate", "required": false, "in": "query", "description": "Start date for statistics (ISO 8601 format)", "schema": { "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date for statistics (ISO 8601 format)", "schema": { "example": "2024-12-31T23:59:59Z", "type": "string" } } ], "responses": { "200": { "description": "Audit statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditStatsResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get audit statistics", "tags": [ "Audit" ] } }, "/api/v1/audit/export": { "get": { "description": "Exports audit logs to CSV format.", "operationId": "exportAuditLogs", "parameters": [ { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "apiKeyId", "required": false, "in": "query", "description": "Filter by API key ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Filter by audit action type(s)", "schema": { "example": [ "CREATE", "UPDATE" ], "type": "array", "items": { "type": "string", "enum": [ "CREATE", "READ", "UPDATE", "DELETE", "LOGIN", "LOGOUT", "LOGIN_FAILED", "PERMISSION_GRANTED", "PERMISSION_DENIED", "EXPORT", "IMPORT", "BULK_UPDATE", "BULK_DELETE", "PASSWORD_CHANGE", "API_KEY_CREATED", "API_KEY_REVOKED", "CERTIFICATE_ISSUED", "CERTIFICATE_REVOKED", "DEPLOYMENT_STARTED", "DEPLOYMENT_COMPLETED", "DEPLOYMENT_FAILED", "DEPLOYMENT_ROLLED_BACK", "DEVICE_ONBOARDING_REJECTED", "DEVICE_CAPABILITY_REPORT_REJECTED", "DEVICE_STATUS_REPORT_REJECTED", "DEVICE_DESIRED_STATE_FETCH_REJECTED", "DEVICE_ONBOARDING_REJECTED_SUMMARY" ] } } }, { "name": "entityType", "required": false, "in": "query", "description": "Filter by entity type(s)", "schema": { "example": [ "Device", "User" ], "type": "array", "items": { "type": "string" } } }, { "name": "entityId", "required": false, "in": "query", "description": "Filter by specific entity ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002", "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "example": true, "type": "boolean" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter logs from this date", "schema": { "format": "date-time", "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter logs until this date", "schema": { "format": "date-time", "example": "2024-12-31T23:59:59Z", "type": "string" } }, { "name": "ipAddress", "required": false, "in": "query", "description": "Filter by IP address", "schema": { "example": "192.168.1.100", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Full-text search in entity name and error message", "schema": { "example": "device-001", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for cursor-based pagination", "schema": { "example": "eyJpZCI6IjEyMzQifQ==", "type": "string" } }, { "name": "maxRecords", "required": false, "in": "query", "description": "Maximum records to export", "schema": { "minimum": 1, "maximum": 100000, "default": 10000, "example": 10000, "type": "number" } } ], "responses": { "200": { "description": "CSV file with audit logs", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Export audit logs", "tags": [ "Audit" ] } }, "/api/v1/audit/{id}": { "get": { "description": "Retrieves a specific audit log entry.", "operationId": "getAuditLog", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Audit log UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Audit log retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Audit log not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get audit log by ID", "tags": [ "Audit" ] } }, "/api/v1/audit/entity/{entityType}/{entityId}": { "get": { "description": "Retrieves audit logs for a specific entity.", "operationId": "getEntityAuditLogs", "parameters": [ { "name": "entityType", "required": true, "in": "path", "description": "Entity type (e.g., Device, User)", "schema": { "example": "Device", "type": "string" } }, { "name": "entityId", "required": true, "in": "path", "description": "Entity UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "apiKeyId", "required": false, "in": "query", "description": "Filter by API key ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Filter by audit action type(s)", "schema": { "example": [ "CREATE", "UPDATE" ], "type": "array", "items": { "type": "string", "enum": [ "CREATE", "READ", "UPDATE", "DELETE", "LOGIN", "LOGOUT", "LOGIN_FAILED", "PERMISSION_GRANTED", "PERMISSION_DENIED", "EXPORT", "IMPORT", "BULK_UPDATE", "BULK_DELETE", "PASSWORD_CHANGE", "API_KEY_CREATED", "API_KEY_REVOKED", "CERTIFICATE_ISSUED", "CERTIFICATE_REVOKED", "DEPLOYMENT_STARTED", "DEPLOYMENT_COMPLETED", "DEPLOYMENT_FAILED", "DEPLOYMENT_ROLLED_BACK", "DEVICE_ONBOARDING_REJECTED", "DEVICE_CAPABILITY_REPORT_REJECTED", "DEVICE_STATUS_REPORT_REJECTED", "DEVICE_DESIRED_STATE_FETCH_REJECTED", "DEVICE_ONBOARDING_REJECTED_SUMMARY" ] } } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "example": true, "type": "boolean" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter logs from this date", "schema": { "format": "date-time", "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter logs until this date", "schema": { "format": "date-time", "example": "2024-12-31T23:59:59Z", "type": "string" } }, { "name": "ipAddress", "required": false, "in": "query", "description": "Filter by IP address", "schema": { "example": "192.168.1.100", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Full-text search in entity name and error message", "schema": { "example": "device-001", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for cursor-based pagination", "schema": { "example": "eyJpZCI6IjEyMzQifQ==", "type": "string" } } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get audit logs for entity", "tags": [ "Audit" ] } }, "/api/v1/audit/user/{userId}": { "get": { "description": "Retrieves audit logs for a specific user.", "operationId": "getUserAuditLogs", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "apiKeyId", "required": false, "in": "query", "description": "Filter by API key ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Filter by audit action type(s)", "schema": { "example": [ "CREATE", "UPDATE" ], "type": "array", "items": { "type": "string", "enum": [ "CREATE", "READ", "UPDATE", "DELETE", "LOGIN", "LOGOUT", "LOGIN_FAILED", "PERMISSION_GRANTED", "PERMISSION_DENIED", "EXPORT", "IMPORT", "BULK_UPDATE", "BULK_DELETE", "PASSWORD_CHANGE", "API_KEY_CREATED", "API_KEY_REVOKED", "CERTIFICATE_ISSUED", "CERTIFICATE_REVOKED", "DEPLOYMENT_STARTED", "DEPLOYMENT_COMPLETED", "DEPLOYMENT_FAILED", "DEPLOYMENT_ROLLED_BACK", "DEVICE_ONBOARDING_REJECTED", "DEVICE_CAPABILITY_REPORT_REJECTED", "DEVICE_STATUS_REPORT_REJECTED", "DEVICE_DESIRED_STATE_FETCH_REJECTED", "DEVICE_ONBOARDING_REJECTED_SUMMARY" ] } } }, { "name": "entityType", "required": false, "in": "query", "description": "Filter by entity type(s)", "schema": { "example": [ "Device", "User" ], "type": "array", "items": { "type": "string" } } }, { "name": "entityId", "required": false, "in": "query", "description": "Filter by specific entity ID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002", "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "example": true, "type": "boolean" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter logs from this date", "schema": { "format": "date-time", "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter logs until this date", "schema": { "format": "date-time", "example": "2024-12-31T23:59:59Z", "type": "string" } }, { "name": "ipAddress", "required": false, "in": "query", "description": "Filter by IP address", "schema": { "example": "192.168.1.100", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Full-text search in entity name and error message", "schema": { "example": "device-001", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for cursor-based pagination", "schema": { "example": "eyJpZCI6IjEyMzQifQ==", "type": "string" } } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get audit logs for user", "tags": [ "Audit" ] } }, "/api/v1/me/auth-event": { "post": { "description": "Emits a tamper-evident audit-log entry for an auth-flow event observed by the BFF (login, refresh, logout, federated, session termination). The signing uses the same AUDIT_HMAC_SECRET as the rest of the audit pipeline.", "operationId": "recordAuthAuditEvent", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEventDto" } } } }, "responses": { "204": { "description": "Audit event recorded" }, "400": { "description": "Invalid payload" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ], "summary": "Record an authentication audit event (FM-494)", "tags": [ "Audit" ] } }, "/api/v1/system-roles": { "get": { "operationId": "SystemRoleController_listRoles", "parameters": [ { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "type": "string" } }, { "name": "role", "required": false, "in": "query", "description": "Filter by role type", "schema": { "type": "string", "enum": [ "SUPERUSER", "SUPPORT" ] } }, { "name": "activeOnly", "required": false, "in": "query", "description": "Filter by active status", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items to return", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemRoleListResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List all system roles", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/superusers": { "get": { "operationId": "SystemRoleController_listSuperusers", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SystemRoleDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all superusers", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/support": { "get": { "operationId": "SystemRoleController_listSupportUsers", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SystemRoleDto" } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all support users", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/counts": { "get": { "operationId": "SystemRoleController_getCounts", "parameters": [], "responses": { "200": { "description": "Counts of superusers and support users" } }, "security": [ { "bearer": [] } ], "summary": "Get counts of system role users", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/users/{userId}": { "get": { "operationId": "SystemRoleController_getUserSystemRoles", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSystemRolesDto" } } } }, "404": { "description": "User not found" } }, "security": [ { "bearer": [] } ], "summary": "Get system roles for a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/users/{userId}/history": { "get": { "operationId": "SystemRoleController_getRoleHistory", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SystemRoleDto" } } } } }, "404": { "description": "User not found" } }, "security": [ { "bearer": [] } ], "summary": "Get role history for a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/grant": { "post": { "operationId": "SystemRoleController_grantRole", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantSystemRoleDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemRoleDto" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Only superusers can grant roles" }, "404": { "description": "User not found" }, "409": { "description": "User already has this role" } }, "security": [ { "bearer": [] } ], "summary": "Grant a system role to a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/superuser/{userId}": { "post": { "operationId": "SystemRoleController_grantSuperuser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemRoleDto" } } } }, "403": { "description": "Only superusers can grant roles" }, "404": { "description": "User not found" }, "409": { "description": "User already has superuser role" } }, "security": [ { "bearer": [] } ], "summary": "Grant superuser role to a user", "tags": [ "System Roles" ] }, "delete": { "operationId": "SystemRoleController_revokeSuperuser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Superuser role revoked" }, "400": { "description": "Cannot revoke own superuser role or last superuser" }, "403": { "description": "Only superusers can revoke roles" }, "404": { "description": "User not found or does not have superuser role" } }, "security": [ { "bearer": [] } ], "summary": "Revoke superuser role from a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/support/{userId}": { "post": { "operationId": "SystemRoleController_grantSupport", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemRoleDto" } } } }, "403": { "description": "Only superusers can grant roles" }, "404": { "description": "User not found" }, "409": { "description": "User already has support role" } }, "security": [ { "bearer": [] } ], "summary": "Grant support role to a user", "tags": [ "System Roles" ] }, "delete": { "operationId": "SystemRoleController_revokeSupport", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Support role revoked" }, "403": { "description": "Only superusers can revoke roles" }, "404": { "description": "User not found or does not have support role" } }, "security": [ { "bearer": [] } ], "summary": "Revoke support role from a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/revoke": { "delete": { "operationId": "SystemRoleController_revokeRole", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSystemRoleDto" } } } }, "responses": { "204": { "description": "Role revoked" }, "400": { "description": "Cannot revoke own superuser role or last superuser" }, "403": { "description": "Only superusers can revoke roles" }, "404": { "description": "User or role not found" } }, "security": [ { "bearer": [] } ], "summary": "Revoke a system role from a user", "tags": [ "System Roles" ] } }, "/api/v1/system-roles/me": { "get": { "operationId": "SystemRoleController_getMySystemRoles", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSystemRolesDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get my system roles", "tags": [ "System Roles" ] } }, "/api/v1/tenant/context": { "get": { "operationId": "TenantSwitchController_getTenantContext", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantContextDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "bearer": [] } ], "summary": "Get current tenant context", "tags": [ "Tenant Switch" ] } }, "/api/v1/tenant/switch": { "post": { "operationId": "TenantSwitchController_switchTenant", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchTenantDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSwitchDto" } } } }, "400": { "description": "Already switched to another tenant" }, "403": { "description": "Not authorized to switch to this tenant" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer": [] } ], "summary": "Switch to a different tenant", "tags": [ "Tenant Switch" ] }, "delete": { "operationId": "TenantSwitchController_returnToDefault", "parameters": [], "responses": { "204": { "description": "Returned to default tenant" }, "400": { "description": "No active tenant switch" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "bearer": [] } ], "summary": "Return to default tenant", "tags": [ "Tenant Switch" ] } }, "/api/v1/tenant/my-tenants": { "get": { "description": "Returns the user's organization memberships. Superusers/support see every organization.", "operationId": "TenantSwitchController_getMyTenants", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyTenantListDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "bearer": [] } ], "summary": "List tenants the current user can access", "tags": [ "Tenant Switch" ] } }, "/api/v1/tenant/switch/history": { "get": { "operationId": "TenantSwitchController_getSwitchHistory", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSwitchListResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "bearer": [] } ], "summary": "Get my tenant switch history", "tags": [ "Tenant Switch" ] } }, "/api/v1/tenant/switches/active": { "get": { "operationId": "TenantSwitchController_getActiveSwitches", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSwitchListResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "bearer": [] } ], "summary": "Get all active tenant switches (admin)", "tags": [ "Tenant Switch" ] } }, "/api/v1/activity/recent": { "get": { "description": "Retrieves recent activity events (deployment status changes, device registrations, certificate issuances) for the current organization. Used by the dashboard.", "operationId": "getRecentActivity", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "default": 50, "type": "number" } } ], "responses": { "200": { "description": "Recent activity retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentActivityResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get recent activity", "tags": [ "Activity" ] } }, "/api/v1/activity": { "get": { "description": "Retrieves activity logs across all users and tenants. Requires Super Admin privileges.", "operationId": "listActivity", "parameters": [ { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Filter by tenant/organization ID", "schema": { "type": "string" } }, { "name": "activityTypes", "required": false, "in": "query", "description": "Filter by activity types", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "targetUserId", "required": false, "in": "query", "description": "Filter by target user ID", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "type": "boolean" } }, { "name": "search", "required": false, "in": "query", "description": "Search text", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination", "schema": { "default": 0, "type": "number" } } ], "responses": { "200": { "description": "Activity list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminActivityListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List all activity", "tags": [ "Activity" ] } }, "/api/v1/activity/users/{userId}": { "get": { "description": "Retrieves activity logs for a specific user. Requires Super Admin privileges.", "operationId": "getActivityByUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Filter by tenant/organization ID", "schema": { "type": "string" } }, { "name": "activityTypes", "required": false, "in": "query", "description": "Filter by activity types", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "targetUserId", "required": false, "in": "query", "description": "Filter by target user ID", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "type": "boolean" } }, { "name": "search", "required": false, "in": "query", "description": "Search text", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination", "schema": { "default": 0, "type": "number" } } ], "responses": { "200": { "description": "User activity retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminActivityListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "User not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get activity by user", "tags": [ "Activity" ] } }, "/api/v1/activity/organizations/{orgId}": { "get": { "description": "Retrieves activity logs for a specific organization/tenant. Requires Super Admin privileges.", "operationId": "getActivityByOrganization", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "userId", "required": false, "in": "query", "description": "Filter by user ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Filter by tenant/organization ID", "schema": { "type": "string" } }, { "name": "activityTypes", "required": false, "in": "query", "description": "Filter by activity types", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "targetUserId", "required": false, "in": "query", "description": "Filter by target user ID", "schema": { "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "success", "required": false, "in": "query", "description": "Filter by success status", "schema": { "type": "boolean" } }, { "name": "search", "required": false, "in": "query", "description": "Search text", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 50, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Offset for pagination", "schema": { "default": 0, "type": "number" } } ], "responses": { "200": { "description": "Organization activity retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminActivityListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get activity by organization", "tags": [ "Activity" ] } }, "/api/v1/activity/organizations/{orgId}/summary": { "get": { "description": "Retrieves activity summary for an organization including active users, login counts, etc. Requires Super Admin privileges.", "operationId": "getOrganizationActivitySummary", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "sinceDays", "required": false, "in": "query", "description": "Number of days to look back", "schema": { "example": 30, "type": "number" } } ], "responses": { "200": { "description": "Organization activity summary retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantActivitySummaryDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" }, "404": { "description": "Organization not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get organization activity summary", "tags": [ "Activity" ] } }, "/api/v1/activity/reports/inactivity": { "get": { "description": "Generates a report of inactive tenants. Requires Super Admin privileges.", "operationId": "getInactivityReport", "parameters": [ { "name": "thresholdDays", "required": false, "in": "query", "description": "Number of days to consider a tenant inactive", "schema": { "example": 30, "type": "number" } } ], "responses": { "200": { "description": "Inactivity report generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InactivityReportDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get inactivity report", "tags": [ "Activity" ] } }, "/api/v1/activity/export": { "post": { "description": "Exports activity logs to CSV or JSON format. Requires Super Admin privileges.", "operationId": "exportActivity", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportActivityDto" } } } }, "responses": { "200": { "description": "Activity exported successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Super Admin required" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Export activity logs", "tags": [ "Activity" ] } }, "/api/v1/ca-certificates": { "get": { "description": "Retrieves a paginated list of CA certificates for the organization.", "operationId": "listCaCertificates", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of CA certificates to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of CA certificates to skip", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination (CA certificate ID)", "schema": { "format": "uuid", "type": "string" } }, { "name": "isRoot", "required": false, "in": "query", "description": "Filter by root CA status", "schema": { "example": true, "type": "boolean" } }, { "name": "isDefault", "required": false, "in": "query", "description": "Filter by default signing CA status", "schema": { "example": true, "type": "boolean" } }, { "name": "includeRetired", "required": false, "in": "query", "description": "Include retired CA certificates", "schema": { "default": false, "example": false, "type": "boolean" } } ], "responses": { "200": { "description": "List of CA certificates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List CA certificates", "tags": [ "CA Certificates" ] }, "post": { "description": "Upload a new CA certificate and private key. The private key will be encrypted at rest.", "operationId": "createCaCertificate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCaCertificateDto" } } } }, "responses": { "201": { "description": "CA certificate uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Invalid certificate or private key format" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "409": { "description": "Conflict - CA certificate with same fingerprint already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Upload CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/{id}": { "get": { "description": "Retrieves detailed information about a specific CA certificate.", "operationId": "getCaCertificate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "CA certificate retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get CA certificate by ID", "tags": [ "CA Certificates" ] }, "delete": { "description": "Permanently delete a CA certificate. Consider retiring instead for audit trail.", "operationId": "deleteCaCertificate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "204": { "description": "CA certificate deleted successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/generate": { "post": { "description": "Generate a new self-signed CA certificate with RSA 4096 key pair. For development and testing only. In production, use a proper PKI.", "operationId": "generateCaCertificate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCaCertificateDto" } } } }, "responses": { "201": { "description": "CA certificate generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "409": { "description": "Conflict - CA certificate with same fingerprint already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Generate self-signed CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/{id}/default": { "patch": { "description": "Set this CA certificate as the default signing CA for new device certificates.", "operationId": "setCaCertificateDefault", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "CA certificate set as default successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Cannot set retired CA as default" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Set as default CA", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/{id}/renew": { "post": { "description": "Extends the expiry of a CA certificate. WFM-internal bookkeeping only; does not re-issue the certificate.", "operationId": "renewCaCertificate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewCaCertificateDto" } } } }, "responses": { "200": { "description": "CA certificate renewed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "400": { "description": "Bad Request - Cannot renew a retired CA certificate" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Renew CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/{id}/download": { "get": { "description": "Download the public CA certificate in PEM format. Private key is never exposed.", "operationId": "downloadCaCertificate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "CA certificate PEM file", "content": { "application/x-pem-file": { "schema": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIBkTCC...\n-----END CERTIFICATE-----" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Download CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/ca-certificates/{id}/retire": { "post": { "description": "Retire a CA certificate. Retired certificates are kept for audit but cannot be used for signing.", "operationId": "retireCaCertificate", "parameters": [ { "name": "x-user-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "CA Certificate UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "CA certificate retired successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaCertificateResponseDto" } } } }, "400": { "description": "Bad Request - CA certificate is already retired" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions (admin only)" }, "404": { "description": "CA certificate not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Retire CA certificate", "tags": [ "CA Certificates" ] } }, "/api/v1/certificates": { "get": { "description": "Retrieves all certificates (device and CA) for the organization with filtering and pagination support.", "operationId": "listCertificates", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by certificate status", "schema": { "default": "all", "type": "string", "enum": [ "all", "valid", "expiring", "expired", "revoked" ] } }, { "name": "type", "required": false, "in": "query", "description": "Filter by certificate type", "schema": { "default": "all", "type": "string", "enum": [ "all", "device", "ca" ] } }, { "name": "deviceId", "required": false, "in": "query", "description": "Filter by device ID (only for device certificates)", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search by subject or fingerprint", "schema": { "example": "CN=device-001", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (1-based)", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "List of certificates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List all certificates", "tags": [ "Certificates" ] } }, "/api/v1/certificates/expiring": { "get": { "description": "Retrieves certificates that are expiring within a specified number of days.", "operationId": "getExpiringCertificates", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Number of days to look ahead for expiring certificates", "schema": { "minimum": 1, "maximum": 365, "default": 30, "example": 30, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (1-based)", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "Expiring certificates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get expiring certificates", "tags": [ "Certificates" ] } }, "/api/v1/certificates/stats": { "get": { "description": "Retrieves certificate statistics including total, valid, expiring, expired, and revoked counts.", "operationId": "getCertificateStats", "parameters": [], "responses": { "200": { "description": "Certificate statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateStatsDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get certificate statistics", "tags": [ "Certificates" ] } }, "/api/v1/registries/git": { "post": { "description": "Creates a new Git registry for the current organization.", "operationId": "createGitRegistry", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGitRegistryDto" } } } }, "responses": { "201": { "description": "Git registry created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "description": "Registry with this name already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create Git registry", "tags": [ "Registries" ] }, "get": { "description": "Retrieves a list of Git registries for the current organization.", "operationId": "listGitRegistries", "parameters": [ { "name": "name", "required": false, "in": "query", "description": "Filter by registry name (partial match)", "schema": { "example": "workloads", "type": "string" } }, { "name": "enabled", "required": false, "in": "query", "description": "Filter by enabled status", "schema": { "example": true, "type": "boolean" } }, { "name": "authType", "required": false, "in": "query", "description": "Filter by authentication type", "schema": { "example": "TOKEN", "type": "string", "enum": [ "NONE", "HTTPS_TOKEN", "SSH_KEY" ] } }, { "name": "search", "required": false, "in": "query", "description": "Search across name and URL", "schema": { "example": "github", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination (registry ID)", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "Git registries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List Git registries", "tags": [ "Registries" ] } }, "/api/v1/registries/git/{id}": { "get": { "description": "Retrieves a Git registry by its unique identifier.", "operationId": "getGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Git registry retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Git registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get Git registry by ID", "tags": [ "Registries" ] }, "patch": { "description": "Updates an existing Git registry.", "operationId": "updateGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGitRegistryDto" } } } }, "responses": { "200": { "description": "Git registry updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Git registry not found" }, "409": { "description": "Registry with this name already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update Git registry", "tags": [ "Registries" ] }, "delete": { "description": "Deletes a Git registry.", "operationId": "deleteGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Git registry deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Git registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete Git registry", "tags": [ "Registries" ] } }, "/api/v1/registries/git/{id}/enable": { "post": { "description": "Enables a Git registry.", "operationId": "enableGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Git registry enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Git registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Enable Git registry", "tags": [ "Registries" ] } }, "/api/v1/registries/git/{id}/disable": { "post": { "description": "Disables a Git registry.", "operationId": "disableGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Git registry disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Git registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable Git registry", "tags": [ "Registries" ] } }, "/api/v1/registries/git/{id}/sync": { "post": { "description": "Triggers a manual sync operation for a Git registry. This clones/pulls the repository and processes application manifests.", "operationId": "syncGitRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Git registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Sync operation completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitRegistrySyncResultDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden\n\nForbidden — caller lacks required permission" }, "404": { "description": "Git registry not found" }, "409": { "description": "Git registry is disabled" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Trigger sync for Git registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci": { "post": { "description": "Creates a new OCI registry for the current organization.", "operationId": "createOciRegistry", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOciRegistryDto" } } } }, "responses": { "201": { "description": "OCI registry created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "description": "Registry with this name already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create OCI registry", "tags": [ "Registries" ] }, "get": { "description": "Retrieves a list of OCI registries for the current organization.", "operationId": "listOciRegistries", "parameters": [ { "name": "name", "required": false, "in": "query", "description": "Filter by registry name (partial match)", "schema": { "example": "container", "type": "string" } }, { "name": "enabled", "required": false, "in": "query", "description": "Filter by enabled status", "schema": { "example": true, "type": "boolean" } }, { "name": "registryType", "required": false, "in": "query", "description": "Filter by registry type", "schema": { "example": "GENERIC", "type": "string", "enum": [ "GENERIC" ] } }, { "name": "authType", "required": false, "in": "query", "description": "Filter by authentication type", "schema": { "example": "BASIC", "type": "string", "enum": [ "NONE", "BASIC", "TOKEN" ] } }, { "name": "search", "required": false, "in": "query", "description": "Search across name, URL, and description", "schema": { "example": "docker", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of items to skip", "schema": { "minimum": 0, "default": 0, "example": 0, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination (registry ID)", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "OCI registries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryListResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List OCI registries", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}": { "get": { "description": "Retrieves an OCI registry by its unique identifier.", "operationId": "getOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OCI registry retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get OCI registry by ID", "tags": [ "Registries" ] }, "patch": { "description": "Updates an existing OCI registry.", "operationId": "updateOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOciRegistryDto" } } } }, "responses": { "200": { "description": "OCI registry updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryResponseDto" } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" }, "409": { "description": "Registry with this name already exists" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update OCI registry", "tags": [ "Registries" ] }, "delete": { "description": "Deletes an OCI registry.", "operationId": "deleteOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "OCI registry deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete OCI registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}/enable": { "post": { "description": "Enables an OCI registry.", "operationId": "enableOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OCI registry enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Enable OCI registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}/disable": { "post": { "description": "Disables an OCI registry.", "operationId": "disableOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "OCI registry disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable OCI registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}/health-check": { "post": { "description": "Triggers a manual health check for an OCI registry. Checks connectivity using the OCI Distribution Spec /v2/ endpoint.", "operationId": "healthCheckOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Health check completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistryHealthCheckResultDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden\n\nForbidden — caller lacks required permission" }, "404": { "description": "OCI registry not found" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Trigger health check for OCI registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}/sync": { "post": { "description": "Triggers a manual sync operation for an OCI registry. This discovers applications in the registry and imports them to the catalog.", "operationId": "syncOciRegistry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Sync operation completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistrySyncResultDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden\n\nForbidden — caller lacks required permission" }, "404": { "description": "OCI registry not found" }, "409": { "description": "OCI registry is disabled" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Trigger sync for OCI registry", "tags": [ "Registries" ] } }, "/api/v1/registries/oci/{id}/sync-history": { "get": { "description": "Returns the 30-day sync history for a tenant OCI registry (newest first). Each entry captures status, counters, errors, duration, and trigger source.", "operationId": "listOciRegistrySyncHistory", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "OCI registry UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "offset", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync history returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OciRegistrySyncHistoryListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "OCI registry not found" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List sync history for OCI registry", "tags": [ "Registries" ] } }, "/api/v1/system/flecs-stores/{organizationId}": { "get": { "description": "Retrieves the FLECS marketplace store configuration for an organization. Requires Super Admin privileges. There is no credential concept for FLECS — the catalog endpoint is public and unauthenticated, so this returns only the store ID, whether it is enabled, and discovery sync diagnostics.", "operationId": "getFlecsStore", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Configuration retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires Super Admin privileges" }, "404": { "description": "No FLECS store configured for this organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get a tenant FLECS store configuration", "tags": [ "FLECS Stores" ] }, "put": { "description": "Upserts the FLECS marketplace store configuration for an organization. The FLECS catalog endpoint is public and unauthenticated, so a store ID plus whether it is enabled is the entire configuration — no credentials are ever required or stored. Requires Super Admin privileges.", "operationId": "upsertFlecsStore", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertFlecsStoreDto" } } } }, "responses": { "200": { "description": "Configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreResponseDto" } } } }, "400": { "description": "Invalid input — for example a missing or non-positive storeId" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires Super Admin privileges" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create or replace a tenant FLECS store configuration", "tags": [ "FLECS Stores" ] }, "delete": { "description": "Soft-deletes the configuration and stops syncing. Requires Super Admin privileges.", "operationId": "deleteFlecsStore", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Configuration removed" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires Super Admin privileges" }, "404": { "description": "No FLECS store configured for this organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Remove a tenant FLECS store configuration", "tags": [ "FLECS Stores" ] } }, "/api/v1/system/flecs-stores/{organizationId}/enable": { "post": { "description": "Activates catalog syncing for the configured store. Requires Super Admin privileges.", "operationId": "enableFlecsStore", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Store enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires Super Admin privileges" }, "404": { "description": "No FLECS store configured for this organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Enable a tenant FLECS store", "tags": [ "FLECS Stores" ] } }, "/api/v1/system/flecs-stores/{organizationId}/disable": { "post": { "description": "Stops catalog syncing while retaining the configuration. Requires Super Admin privileges.", "operationId": "disableFlecsStore", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Store disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreResponseDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires Super Admin privileges" }, "404": { "description": "No FLECS store configured for this organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Disable a tenant FLECS store", "tags": [ "FLECS Stores" ] } }, "/api/v1/flecs-store/sync": { "post": { "description": "Triggers an immediate sync of the current organization’s FLECS marketplace store, ahead of the automatic 5-minute schedule. Returns null when no store is configured, or when the FLECS catalog discovery call itself failed before the underlying OCI sync could start (see the store’s lastSyncError for the reason).", "operationId": "triggerFlecsStoreSync", "parameters": [], "responses": { "200": { "description": "Sync operation completed (or discovery failed — see lastSyncError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreSyncResultDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Trigger a manual sync for the tenant FLECS store", "tags": [ "FLECS Stores" ] } }, "/api/v1/flecs-store/sync/progress": { "get": { "description": "Returns the current sync run’s per-repository status (checking/added/updated/rejected), if a run is currently in flight. registryId is null when nothing is running — the expected state between the automatic 5-minute ticks, not an error.", "operationId": "getFlecsStoreSyncProgress", "parameters": [], "responses": { "200": { "description": "Progress returned (idle shape when nothing is running)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreSyncProgressDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Live per-repository sync progress for the tenant FLECS store", "tags": [ "FLECS Stores" ] } }, "/api/v1/flecs-store/sync-history": { "get": { "description": "Returns the sync history for the current organization’s FLECS marketplace store (newest first). Each entry includes the per-product breakdown of catalog products imported vs. skipped in that run, and why a product was skipped.", "operationId": "listFlecsSyncHistory", "parameters": [ { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "offset", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync history returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlecsStoreSyncHistoryListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "503": { "description": "Application service unavailable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List sync history for the tenant FLECS store", "tags": [ "FLECS Stores" ] } }, "/api/v1/applications": { "get": { "description": "Retrieves a paginated list of applications with optional filtering by category, vendor, and deployment profile.", "operationId": "listApplications", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search term to filter applications by name, description, or vendor", "schema": { "example": "mosquitto", "type": "string" } }, { "name": "category", "required": false, "in": "query", "description": "Filter by category", "schema": { "example": "IoT", "type": "string" } }, { "name": "vendor", "required": false, "in": "query", "description": "Filter by vendor", "schema": { "example": "Eclipse Foundation", "type": "string" } }, { "name": "deploymentProfile", "required": false, "in": "query", "description": "Filter by deployment profile type", "schema": { "type": "string", "enum": [ "DOCKER_COMPOSE", "HELM", "K8S_MANIFEST", "PODMAN", "QUADLET" ] } }, { "name": "availability", "required": false, "in": "query", "description": "Filter by availability status", "schema": { "type": "string", "enum": [ "AVAILABLE", "SOURCE_UNAVAILABLE" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return", "schema": { "minimum": 1, "default": 20, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of results to skip", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "name", "updatedAt", "createdAt" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List of applications retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationListResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "503": { "description": "Service unavailable - Application service is not reachable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List applications", "tags": [ "Applications" ] } }, "/api/v1/applications/categories": { "get": { "description": "Retrieves a list of unique application categories", "operationId": "getCategories", "parameters": [], "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get unique categories", "tags": [ "Applications" ] } }, "/api/v1/applications/vendors": { "get": { "description": "Retrieves a list of unique application vendors", "operationId": "getVendors", "parameters": [], "responses": { "200": { "description": "Vendors retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorsResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get unique vendors", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}": { "get": { "description": "Retrieves detailed information about a specific application including all versions.", "operationId": "getApplication", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "Application retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationDetailsResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Application not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get application by ID", "tags": [ "Applications" ] }, "delete": { "description": "Soft-deletes the application and all of its versions. Refused with 409 if any version has active deployments, or if the application is still provided by a live registry source. Restricted to superadmins.", "operationId": "deleteApplication", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Application deleted" }, "403": { "description": "Superadmin access required" }, "404": { "description": "Application not found" }, "409": { "description": "Active deployments still reference the application, or a live registry source still provides it" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete an application package", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}/versions": { "get": { "description": "Retrieves all versions for an application package.", "operationId": "getApplicationVersions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } } ], "responses": { "200": { "description": "Application versions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationVersionsResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Application not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get application versions", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}/versions/{version}": { "get": { "description": "Retrieves a specific version of an application.", "operationId": "getApplicationVersion", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "version", "required": true, "in": "path", "description": "Version string (semver)", "schema": { "example": "2.0.18", "type": "string" } } ], "responses": { "200": { "description": "Application version retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Version not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get specific application version", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}/deployments": { "get": { "description": "Retrieves all deployments across all versions of an application package.", "operationId": "listApplicationDeployments", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max items to return (default 20)", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of items to skip (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Deployments retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Application not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List deployments for an application", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}/versions/{version}/deployments": { "get": { "description": "Retrieves deployments for a specific version of an application.", "operationId": "listVersionDeployments", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "version", "required": true, "in": "path", "description": "Version string", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max items to return (default 20)", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Number of items to skip (default 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Deployments retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List deployments for a specific version", "tags": [ "Applications" ] } }, "/api/v1/applications/{id}/icon": { "get": { "description": "Retrieves the icon image for an application.", "operationId": "getApplicationIcon", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Application package UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Icon retrieved successfully", "content": { "image/png": {}, "image/svg+xml": {}, "image/jpeg": {} } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Icon not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get application icon", "tags": [ "Applications" ] } }, "/api/v1/deployments": { "get": { "description": "Retrieves a paginated list of deployments with optional filtering.", "operationId": "listDeployments", "parameters": [], "responses": { "200": { "description": "List of deployments retrieved successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "503": { "description": "Service unavailable - Deployment service is not reachable" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List deployments", "tags": [ "Deployments" ] }, "post": { "description": "Creates a new deployment.", "operationId": "createDeployment", "parameters": [], "responses": { "201": { "description": "Deployment created successfully" }, "400": { "description": "Bad request - Invalid deployment data" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create a deployment", "tags": [ "Deployments" ] } }, "/api/v1/deployments/stats": { "get": { "description": "Retrieves deployment statistics for the organization.", "operationId": "getDeploymentStats", "parameters": [], "responses": { "200": { "description": "Deployment statistics retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get deployment statistics", "tags": [ "Deployments" ] } }, "/api/v1/deployments/awaiting-removal": { "get": { "description": "Lists deployments that were deleted but that at least one device has not yet confirmed removing. A deployment leaves this list only when every device has reported `removed`; a device that reported `failed` keeps it here, because the workload may still be running.", "operationId": "listDeploymentsAwaitingRemoval", "parameters": [], "responses": { "200": { "description": "Deployments awaiting removal retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List deployments awaiting removal confirmation", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}": { "get": { "description": "Retrieves detailed information about a specific deployment.", "operationId": "getDeployment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deployment retrieved successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get deployment by ID", "tags": [ "Deployments" ] }, "put": { "description": "Updates an existing deployment.", "operationId": "updateDeployment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deployment updated successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update a deployment", "tags": [ "Deployments" ] }, "delete": { "description": "Withdraws a deployment and requests its removal from every targeted device. FM-844: this does NOT confirm removal — the device is the authority and reports `removing` -> `removed`/`failed` over the Margo status endpoint. Poll `GET /api/v1/deployments/:id/removal-status` to see which devices have actually confirmed.", "operationId": "deleteDeployment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Removal requested successfully; device confirmation is reported separately" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete a deployment", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/start": { "post": { "description": "Starts a deployment, triggering workload distribution to target devices.", "operationId": "startDeployment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deployment started successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Start a deployment", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/stop": { "post": { "description": "Stops a running deployment.", "operationId": "stopDeployment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deployment stopped successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Stop a deployment", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/removal-status": { "get": { "description": "Reports, per device, whether a deleted deployment has actually been removed from the client. Deleting a deployment only requests removal; the device confirms it by reporting `removed` (or `failed`) over the Margo status endpoint. Devices that have been asked and have not answered are reported as `awaiting`, which is neither a success nor a failure.", "operationId": "getDeploymentRemovalStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Removal status retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get removal status", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/rollout-status": { "get": { "description": "Retrieves the current rollout phase, batch progress and per-status instance counts.", "operationId": "getRolloutStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Rollout status retrieved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get rollout status", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/rollout/initialize": { "post": { "description": "Assigns deployment instances to batches (rolling) or to the canary cohort (canary).", "operationId": "initializeRollout", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Rollout initialized successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Initialize a rollout", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/rollout/start": { "post": { "description": "Begins deploying the first batch (or canary cohort) of an initialized rollout.", "operationId": "startRollout", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Rollout started successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Start a rollout", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/promote": { "post": { "description": "Promotes the canary cohort, progressing the rollout to the remaining devices.", "operationId": "promoteCanary", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Canary promoted successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Promote a canary rollout", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/approve-batch": { "post": { "description": "Approves the next wave for a rolling rollout configured for manual approval.", "operationId": "approveBatch", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Batch approved successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Approve the next rollout batch", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/pause": { "post": { "description": "Pauses the rollout at the current batch boundary.", "operationId": "pauseRollout", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Rollout paused successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Pause a rollout", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/resume": { "post": { "description": "Resumes a paused rollout from its current phase.", "operationId": "resumeRollout", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Rollout resumed successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Resume a rollout", "tags": [ "Deployments" ] } }, "/api/v1/deployments/{id}/rollback": { "post": { "description": "Aborts the in-flight rollout and marks it rolled back. This does not redeploy a previous application version.", "operationId": "triggerRollback", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deployment UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRollbackDto" } } } }, "responses": { "200": { "description": "Rollback triggered successfully" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Deployment not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Abort an in-flight rollout", "tags": [ "Deployments" ] } }, "/api/v1/devices/rollback-version": { "post": { "description": "Redeploys the application version each matching device ran before its current one. Devices with no distinct previous version are reported as skipped rather than failing the batch. This does not abort an in-flight rollout — see the deployment rollback route.", "operationId": "rollbackDevicesBySelector", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackDevicesBySelectorDto" } } } }, "responses": { "200": { "description": "Rollback evaluated for every matching device" }, "400": { "description": "deviceSelector missing or malformed" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "No devices matched the selector" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Roll back a group of devices to their previous application version", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/rollback-version": { "post": { "description": "Redeploys the application version this device ran before its current one, producing a new manifest version (never reusing or decrementing). Returns 409 when the device has no distinct previous version. This does not abort an in-flight rollout.", "operationId": "rollbackDeviceVersion", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackDeviceVersionDto" } } } }, "responses": { "200": { "description": "Device rolled back to its previous version" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" }, "409": { "description": "No previous version to roll back to" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Roll back a device to its previous application version", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/rollback-target": { "get": { "description": "Returns which application version the device would be rolled back to, or a machine-readable code explaining why it cannot be. Read-only — nothing is deployed. The resolution rule lives on the server so clients need not re-derive it.", "operationId": "getDeviceRollbackTarget", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "applicationPackageId", "required": false, "in": "query", "description": "Scope the preview to one application package. Mirrors the rollback body so a preview cannot name a version the rollback would not apply.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rollback target resolved (or reported unavailable)" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Resolve the rollback target for a device", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/version-history": { "get": { "description": "Recorded deployment version lineage for the device, newest first. Backs the confirm dialog that names both versions before a rollback.", "operationId": "getDeviceVersionHistory", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Version history retrieved" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get a device deployment version history", "tags": [ "Devices" ] } }, "/api/v1/devices/{id}/telemetry": { "get": { "description": "Retrieves metric snapshots for a device within a time range, with optional downsampling.", "operationId": "getDeviceTelemetry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "Start of time range (ISO 8601)", "schema": { "example": "2026-03-17T00:00:00Z", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "End of time range (ISO 8601)", "schema": { "example": "2026-03-18T00:00:00Z", "type": "string" } }, { "name": "interval", "required": false, "in": "query", "description": "Aggregation interval for downsampling", "schema": { "default": "1m", "type": "string", "enum": [ "1m", "5m", "1h", "1d" ] } } ], "responses": { "200": { "description": "Telemetry data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryListResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get device telemetry", "tags": [ "Device Telemetry" ] } }, "/api/v1/devices/{id}/telemetry/latest": { "get": { "description": "Retrieves the most recent metric snapshot with computed percentages.", "operationId": "getDeviceTelemetryLatest", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Latest telemetry retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSnapshotDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found or no telemetry data" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get latest device telemetry", "tags": [ "Device Telemetry" ] } }, "/api/v1/devices/{id}/metrics/raw": { "get": { "description": "Retrieves every fm_device_* metric series currently reporting for this device, unmapped onto the fixed CPU/memory/disk field set the curated telemetry endpoints project onto (FM-1148). Useful for confirming telemetry is actually arriving when a device sends a metric shape the curated cards don't fully cover.", "operationId": "getDeviceRawMetrics", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Raw metrics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawMetricsResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get every raw device metric currently reported", "tags": [ "Device Telemetry" ] } }, "/api/v1/devices/{id}/logs": { "get": { "description": "Retrieves log entries for a device with cursor-based pagination, newest first.", "operationId": "getDeviceLogs", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "severity", "required": false, "in": "query", "description": "Filter by severity level", "schema": { "type": "string", "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of log entries to return. Raised to 1000 (FM-772) to guarantee at least the last 1000 lines are retrievable for an active device.", "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "number" } }, { "name": "before", "required": false, "in": "query", "description": "Cursor for pagination (timestamp of last entry)", "schema": { "example": "2026-03-17T12:00:00Z", "type": "string" } }, { "name": "source", "required": false, "in": "query", "description": "Filter by log source (container name, service, or \"system\")", "schema": { "example": "my-container", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Full-text search against the log message body. Matched case-insensitively as a substring, server-side, against Loki (index-backed by the label selector; the search itself is a line filter evaluated before JSON parsing). Composes with `severity` and `source`.", "schema": { "example": "connection refused", "type": "string" } } ], "responses": { "200": { "description": "Log entries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogListResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get device logs", "tags": [ "Device Telemetry" ] } }, "/api/v1/devices/{id}/logs/sources": { "get": { "description": "Retrieves the distinct workload/container/service `source` values seen for this device within the log retention window, so the UI can populate a workload picker without scanning the full log.", "operationId": "getDeviceLogSources", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Log sources retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSourcesResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get distinct device log sources", "tags": [ "Device Telemetry" ] } }, "/api/v1/devices/{id}/logs/stream": { "get": { "description": "Server-Sent Events stream of new log lines for a device as they arrive, honoring the same `severity`/`source`/`q` filters as the paged `/logs` endpoint (FM-773, composed through the same `buildDeviceLogQuery()` builder). Implemented as short-interval polling of Loki's `query_range`, re-emitted as SSE — see `LogStreamService` for why. Named events on the stream: `log` (a `LogEntryDto`, `id` set to a resumable `:` cursor — reconnect with the `Last-Event-ID` header to resume exactly after it, which browsers do automatically on a dropped connection), `heartbeat` (keepalive, ~15s, survives idle proxies), `skip` (`{ skipped: number }`, emitted when the server had to drop the oldest lines of a poll tick under backpressure rather than buffer unboundedly), `error` (a transient upstream query failure; the stream keeps polling), and `permission-revoked` (the stream ends immediately after — the caller's `TELEMETRY_READ` permission is re-checked periodically, not only at connect). Subject to per-organization and per-user concurrent-connection caps — 429 Too Many Requests when exceeded, returned as an ordinary JSON response before any SSE headers are sent.", "operationId": "streamDeviceLogs", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Device UUID", "schema": { "format": "uuid", "type": "string" } }, { "name": "severity", "required": false, "in": "query", "description": "Filter by severity level", "schema": { "type": "string", "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ] } }, { "name": "source", "required": false, "in": "query", "description": "Filter by log source (container name, service, or \"system\")", "schema": { "example": "my-container", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Full-text search against the log message body, same semantics as the paged endpoint.", "schema": { "example": "connection refused", "type": "string" } }, { "name": "last-event-id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "text/event-stream of device log events" }, "403": { "description": "Forbidden — caller lacks required permission" }, "404": { "description": "Device not found" }, "429": { "description": "Too many concurrent log stream connections for this organization or user" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Stream device logs (follow mode)", "tags": [ "Device Telemetry" ] } }, "/api/v1/fleet/health": { "get": { "description": "Returns aggregated health metrics across all devices in the organization.", "operationId": "getFleetHealth", "parameters": [], "responses": { "200": { "description": "Fleet health summary retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetHealthResponseDto" } } } }, "403": { "description": "Forbidden — caller lacks required permission" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get fleet health summary", "tags": [ "Fleet Health" ] } }, "/api/v1/realtime/ticket": { "post": { "description": "Returns a short-lived, single-use ticket bound to the caller and the resolved organization. Redeem it once as `wss:///ws?ticket=`. A ticket is consumed on redemption, so each connection attempt — including every reconnect — requires a freshly minted ticket.", "operationId": "createWebSocketTicket", "parameters": [], "responses": { "201": { "description": "Ticket minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WsTicketResponseDto" } } } }, "401": { "description": "Unauthorized — invalid or missing authentication" }, "403": { "description": "Forbidden — no accessible organization context" } }, "security": [ { "bearer": [] } ], "summary": "Mint a WebSocket handshake ticket", "tags": [ "Realtime" ] } }, "/api/v1/alert-rules": { "get": { "description": "Lists every alert rule in the caller’s organization, newest first.", "operationId": "listAlertRules", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleResponseDto" } } } } } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List alert rules", "tags": [ "Alerts" ] }, "post": { "description": "The expression is validated against the alert DSL at write time — a malformed rule is rejected here rather than silently never firing.", "operationId": "createAlertRule", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertRuleDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleResponseDto" } } } }, "400": { "description": "Malformed expression, or scope/target mismatch" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create an alert rule", "tags": [ "Alerts" ] } }, "/api/v1/alert-rules/deliveries": { "get": { "description": "Alert occurrences with their fired/resolved timestamps and delivery outcome, newest first. Optionally filtered by rule or device.", "operationId": "listAlertDeliveries", "parameters": [ { "name": "ruleId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "deviceId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Default 50, maximum 200", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertDeliveryListResponseDto" } } } } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List alert delivery history", "tags": [ "Alerts" ] } }, "/api/v1/alert-rules/{id}": { "get": { "operationId": "getAlertRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleResponseDto" } } } }, "404": { "description": "No such rule in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get an alert rule", "tags": [ "Alerts" ] }, "patch": { "operationId": "updateAlertRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertRuleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleResponseDto" } } } }, "404": { "description": "No such rule in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update an alert rule", "tags": [ "Alerts" ] }, "delete": { "description": "Cascades to the rule’s target wiring and its delivery history.", "operationId": "deleteAlertRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "No such rule in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete an alert rule", "tags": [ "Alerts" ] } }, "/api/v1/alert-rules/{id}/test-fire": { "post": { "description": "Dispatches a test notification through each configured target so an operator can confirm delivery actually works before relying on it. Creates no AlertDelivery record, so a test never consumes the rule’s open-alert slot and cannot suppress a subsequent real alert. Per-target outcomes are reported individually — one broken endpoint does not hide the rest.", "operationId": "testFireAlertRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestFireResponseDto" } } } }, "404": { "description": "No such rule in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Send a test notification to a rule’s targets", "tags": [ "Alerts" ] } }, "/api/v1/notification-targets": { "get": { "description": "Lists every notification target in the caller’s organization. Webhook signing secrets are never included — only a boolean indicating whether one is configured.", "operationId": "listNotificationTargets", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationTargetResponseDto" } } } } } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "List notification targets", "tags": [ "Alerts" ] }, "post": { "description": "A WEBHOOK target is assigned an HMAC-SHA256 signing secret when none is supplied. That secret is returned in THIS response only and is never readable again.", "operationId": "createNotificationTarget", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationTargetDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedNotificationTargetResponseDto" } } } }, "400": { "description": "Missing channel-specific field, or a webhook URL pointing at a private, loopback, link-local or in-cluster address" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Create a notification target", "tags": [ "Alerts" ] } }, "/api/v1/notification-targets/{id}": { "get": { "operationId": "getNotificationTarget", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTargetResponseDto" } } } }, "404": { "description": "No such target in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Get a notification target", "tags": [ "Alerts" ] }, "patch": { "description": "The channel is immutable — switching transports would leave the stored config mismatched and would retroactively mislabel every delivery already recorded against the target.", "operationId": "updateNotificationTarget", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationTargetDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTargetResponseDto" } } } }, "404": { "description": "No such target in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Update a notification target", "tags": [ "Alerts" ] }, "delete": { "description": "Cascades to the target’s wiring on every alert rule and to its delivery history.", "operationId": "deleteNotificationTarget", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "No such target in the caller’s organization" } }, "security": [ { "api-key": [] }, { "bearer": [] } ], "summary": "Delete a notification target", "tags": [ "Alerts" ] } } }, "info": { "title": "Margo WFM API", "description": "\n## Overview\nMargo Workload Fleet Manager (WFM) REST API for managing edge device fleets and workload deployments.\n\n## Authentication\nAll API endpoints require authentication via Bearer token or API key.\n\n### Bearer Token\n```\nAuthorization: Bearer \n```\n\n### API Key\n```\nX-API-Key: \n```\n\n## Rate Limiting\n- Default: 100 requests per minute\n- Burst: 20 requests per second\n\n## Pagination\nList endpoints support pagination via `page` and `pageSize` query parameters:\n- `page`: Page number (default: 1)\n- `pageSize`: Items per page (default: 20, max: 100)\n\n## Filtering\nMost list endpoints support filtering via query parameters specific to the resource.\n\n## Error Responses\nAll errors follow RFC 7807 Problem Details format.\n ", "version": "2.54.2", "contact": { "name": "Margo WFM Team", "url": "https://github.com/fleet-manager", "email": "support@fleet-manager.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "tags": [ { "name": "Devices", "description": "Device management operations" }, { "name": "Device Certificates", "description": "Device certificate management" }, { "name": "Certificates", "description": "Certificate overview and statistics" }, { "name": "CA Certificates", "description": "Certificate Authority (CA) management" }, { "name": "Groups", "description": "Device group management" }, { "name": "Organizations", "description": "Organization management" }, { "name": "Users", "description": "User management" }, { "name": "Organization Members", "description": "Organization member management" }, { "name": "Roles", "description": "Role-based access control" }, { "name": "API Keys", "description": "API key management" }, { "name": "Invitations", "description": "User invitation management" }, { "name": "Public Invitations", "description": "Public invitation endpoints (no authentication required)" }, { "name": "Audit", "description": "Audit log operations" } ], "servers": [ { "url": "http://localhost:3000", "description": "Development" }, { "url": "https://api.fleet-manager.io", "description": "Production" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "JWT authentication token" }, "api-key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for service-to-service communication" } }, "schemas": { "HealthCheckResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "service": { "type": "string", "example": "api-gateway" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "status", "service", "timestamp" ] }, "LivenessResponse": { "type": "object", "properties": { "live": { "type": "boolean", "example": true } }, "required": [ "live" ] }, "FederationSyncResponseDto": { "type": "object", "properties": { "usersProcessed": { "type": "number", "description": "Number of brokered Keycloak users mapped to a WFM user and reconciled", "example": 42 }, "added": { "type": "number", "description": "Total FEDERATED memberships created", "example": 3 }, "updated": { "type": "number", "description": "Total memberships whose role changed", "example": 1 }, "removed": { "type": "number", "description": "Total FEDERATED memberships removed", "example": 2 }, "skipped": { "type": "number", "description": "Number of Keycloak users skipped (no WFM user, no Entra attributes, or a per-user error)", "example": 5 } }, "required": [ "usersProcessed", "added", "updated", "removed", "skipped" ] }, "FederatedGroupMappingResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique mapping identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "organizationId": { "type": "string", "description": "Organization the mapping grants membership in", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "provider": { "type": "string", "description": "Identity provider that supplies the app-role / group", "enum": [ "ENTRA", "LDAP" ], "example": "ENTRA" }, "externalId": { "type": "string", "description": "Provider role value or group id carried in the token claim", "example": "fleet-operators" }, "externalKind": { "type": "string", "description": "Kind of external identifier (application role or group)", "enum": [ "APP_ROLE", "GROUP" ], "example": "GROUP" }, "externalLabel": { "type": "string", "description": "Human-readable label captured at mapping time", "example": "Fleet Operators (Entra group)" }, "roleId": { "type": "string", "description": "WFM role granted to users matching this mapping", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "enabled": { "type": "boolean", "description": "Whether the mapping is active (resolved at login time)", "example": true }, "createdById": { "type": "string", "description": "Id of the user who created the mapping", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440003" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the mapping was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the mapping was last updated", "example": "2024-06-20T14:45:00Z" } }, "required": [ "id", "organizationId", "provider", "externalId", "externalKind", "roleId", "enabled", "createdAt", "updatedAt" ] }, "FederatedGroupMappingListResponseDto": { "type": "object", "properties": { "items": { "description": "List of federated group mappings", "type": "array", "items": { "$ref": "#/components/schemas/FederatedGroupMappingResponseDto" } }, "total": { "type": "number", "description": "Total number of mappings matching the query", "example": 3 } }, "required": [ "items", "total" ] }, "CreateFederatedGroupMappingDto": { "type": "object", "properties": { "provider": { "type": "string", "description": "Identity provider that supplies the app-role / group", "enum": [ "ENTRA", "LDAP" ], "example": "ENTRA" }, "externalId": { "type": "string", "description": "Provider role value or group id carried in the token claim", "example": "fleet-operators", "maxLength": 255 }, "externalKind": { "type": "string", "description": "Kind of external identifier (application role or group)", "enum": [ "APP_ROLE", "GROUP" ], "example": "GROUP" }, "externalLabel": { "type": "string", "description": "Human-readable label captured at mapping time", "example": "Fleet Operators (Entra group)", "maxLength": 255 }, "organizationId": { "type": "string", "description": "Organization the mapping grants membership in", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "roleId": { "type": "string", "description": "WFM role granted to users matching this mapping", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "enabled": { "type": "boolean", "description": "Whether the mapping is active (resolved at login time)", "default": true, "example": true } }, "required": [ "provider", "externalId", "externalKind", "organizationId", "roleId" ] }, "UpdateFederatedGroupMappingDto": { "type": "object", "properties": { "externalId": { "type": "string", "description": "Provider role value or group id carried in the token claim", "example": "fleet-operators", "maxLength": 255 }, "externalKind": { "type": "string", "description": "Kind of external identifier (application role or group)", "enum": [ "APP_ROLE", "GROUP" ], "example": "GROUP" }, "externalLabel": { "type": "string", "description": "Human-readable label captured at mapping time", "example": "Fleet Operators (Entra group)", "maxLength": 255 }, "roleId": { "type": "string", "description": "WFM role granted to users matching this mapping", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "enabled": { "type": "boolean", "description": "Whether the mapping is active (resolved at login time)", "default": true, "example": true } } }, "DeviceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique device identifier (UUID)", "example": "550e8400-e29b-41d4-a716-446655440000", "format": "uuid" }, "clientId": { "type": "string", "description": "Client-provided device identifier", "example": "edge-device-001" }, "name": { "type": "string", "description": "Human-readable device name", "example": "Production Edge Gateway 1" }, "status": { "type": "string", "description": "Current device status", "example": "ONLINE", "enum": [ "ONLINE", "OFFLINE", "PENDING", "ERROR" ] }, "capabilities": { "type": "object", "description": "Device capabilities as reported during onboarding", "example": { "cpu": { "cores": 4, "architecture": "arm64" }, "memory": { "total": 8192 }, "containers": { "runtime": "containerd" } }, "additionalProperties": true }, "labels": { "type": "object", "description": "Key-value labels for device organization and filtering", "example": { "environment": "production", "region": "us-west", "tier": "edge" }, "additionalProperties": { "type": "string" } }, "lastSeenAt": { "format": "date-time", "type": "string", "description": "Timestamp of last communication from device", "example": "2024-01-15T10:30:00Z" }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when device was registered", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp of last device update", "example": "2024-01-15T10:30:00Z" }, "reportedDeviceId": { "type": "string", "description": "Margo self-reported DeviceId (properties.id from the device capabilities manifest). Unique per organization among non-deleted devices — null if this device has never reported capabilities, or if it collided with another device already holding the same value (FM-1043) and its write was rejected.", "example": "wm-uc20-m3000-ax4b14pc7500001" }, "cpuUsagePercent": { "type": "number", "description": "Latest reported CPU usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.", "example": 42.5, "nullable": true }, "memoryUsagePercent": { "type": "number", "description": "Latest reported memory usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.", "example": 67.2, "nullable": true }, "diskUsagePercent": { "type": "number", "description": "Latest reported disk usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.", "example": 55.1, "nullable": true }, "runningWorkloadCount": { "type": "number", "description": "Count of non-removed deployment instances currently targeting this device (FM-770). Always a real count, independent of telemetry availability.", "example": 3, "nullable": true } }, "required": [ "id", "clientId", "status", "capabilities", "labels", "createdAt", "updatedAt" ] }, "DeviceListResponseDto": { "type": "object", "properties": { "data": { "description": "Array of device objects", "type": "array", "items": { "$ref": "#/components/schemas/DeviceResponseDto" } }, "total": { "type": "number", "description": "Total number of devices matching the filter criteria", "example": 150, "minimum": 0 }, "hasMore": { "type": "boolean", "description": "Indicates if there are more devices available", "example": true }, "nextCursor": { "type": "string", "description": "Cursor for fetching the next page of results", "example": "eyJpZCI6IjEyMzQifQ==" } }, "required": [ "data", "total", "hasMore" ] }, "RecentActivityItemDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event ID" }, "type": { "type": "string", "description": "Event type", "enum": [ "deployment.status", "device.registered", "certificate.issued", "registry-sync-failed" ] }, "message": { "type": "string", "description": "Human-readable event message" }, "timestamp": { "format": "date-time", "type": "string", "description": "When the event occurred" }, "metadata": { "type": "object", "description": "Additional metadata about the event" } }, "required": [ "id", "type", "message", "timestamp" ] }, "RecentActivityResponseDto": { "type": "object", "properties": { "items": { "description": "Recent activity items", "type": "array", "items": { "$ref": "#/components/schemas/RecentActivityItemDto" } } }, "required": [ "items" ] }, "UpdateDeviceDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable device name", "example": "Production Edge Gateway 1", "maxLength": 255 }, "labels": { "type": "object", "description": "Key-value labels for device organization and filtering", "example": { "environment": "production", "region": "us-west", "tier": "edge" }, "additionalProperties": { "type": "string" } } } }, "DeviceCertificateResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique certificate identifier (UUID)", "example": "550e8400-e29b-41d4-a716-446655440000", "format": "uuid" }, "deviceId": { "type": "string", "description": "Device ID this certificate belongs to", "example": "550e8400-e29b-41d4-a716-446655440001", "format": "uuid" }, "fingerprint": { "type": "string", "description": "SHA-256 fingerprint of the certificate", "example": "A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2" }, "subject": { "type": "string", "description": "Certificate subject (Distinguished Name)", "example": "CN=edge-device-001,O=Margo WFM,OU=Devices" }, "issuer": { "type": "string", "description": "Certificate issuer (Distinguished Name)", "example": "CN=Margo Root CA,O=Margo WFM,OU=Certificate Authority" }, "notBefore": { "format": "date-time", "type": "string", "description": "Certificate validity start date", "example": "2024-01-01T00:00:00Z" }, "notAfter": { "format": "date-time", "type": "string", "description": "Certificate validity end date (expiration)", "example": "2025-01-01T00:00:00Z" }, "revoked": { "type": "boolean", "description": "Whether the certificate has been revoked", "example": false }, "revokedAt": { "format": "date-time", "type": "string", "description": "Date when the certificate was revoked", "example": "2024-06-01T00:00:00Z" }, "revokeReason": { "type": "string", "description": "Reason for certificate revocation", "example": "Key compromise", "enum": [ "Key compromise", "CA compromise", "Affiliation changed", "Superseded", "Cessation of operation", "Certificate hold", "Other" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the certificate was issued", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id", "deviceId", "fingerprint", "subject", "issuer", "notBefore", "notAfter", "revoked", "createdAt" ] }, "DeviceCertificateListResponseDto": { "type": "object", "properties": { "data": { "description": "List of device certificates", "type": "array", "items": { "$ref": "#/components/schemas/DeviceCertificateResponseDto" } }, "total": { "type": "number", "description": "Total number of certificates for this device", "example": 3 } }, "required": [ "data", "total" ] }, "RevokeCertificateDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for revoking the certificate", "enum": [ "Key compromise", "CA compromise", "Affiliation changed", "Superseded", "Cessation of operation", "Certificate hold", "Other" ], "example": "Key compromise" }, "notes": { "type": "string", "description": "Additional notes about the revocation (required if reason is \"Other\")", "example": "Device was stolen from warehouse", "maxLength": 1000 } }, "required": [ "reason" ] }, "RenewCertificateDto": { "type": "object", "properties": { "validityDays": { "type": "number", "description": "Number of days to extend the certificate validity from today", "example": 365, "minimum": 1, "maximum": 3650, "default": 365 } } }, "StatusBreakdownDto": { "type": "object", "properties": { "online": { "type": "number", "description": "Number of online devices", "example": 45 }, "offline": { "type": "number", "description": "Number of offline devices", "example": 5 }, "pending": { "type": "number", "description": "Number of pending devices", "example": 2 }, "error": { "type": "number", "description": "Number of devices in error state", "example": 1 } }, "required": [ "online", "offline", "pending", "error" ] }, "FleetStatsResponseDto": { "type": "object", "properties": { "totalDevices": { "type": "number", "description": "Total number of devices in the fleet", "example": 150 }, "byStatus": { "description": "Status breakdown of all devices", "allOf": [ { "$ref": "#/components/schemas/StatusBreakdownDto" } ] }, "labelKeys": { "description": "List of all label keys used in the organization", "example": [ "environment", "region", "tier" ], "type": "array", "items": { "type": "string" } }, "unlabeledDeviceCount": { "type": "number", "description": "Number of devices with no labels assigned", "example": 3 } }, "required": [ "totalDevices", "byStatus", "labelKeys", "unlabeledDeviceCount" ] }, "LabelKeysResponseDto": { "type": "object", "properties": { "keys": { "description": "List of unique label keys used in the organization", "example": [ "environment", "region", "tier", "version" ], "type": "array", "items": { "type": "string" } } }, "required": [ "keys" ] }, "LabelValuesResponseDto": { "type": "object", "properties": { "key": { "type": "string", "description": "The label key", "example": "environment" }, "values": { "description": "List of unique values for this label key", "example": [ "production", "staging", "development" ], "type": "array", "items": { "type": "string" } } }, "required": [ "key", "values" ] }, "LabelGroupDto": { "type": "object", "properties": { "value": { "type": "string", "description": "Label value", "example": "production" }, "count": { "type": "number", "description": "Number of devices with this label value", "example": 25 }, "byStatus": { "description": "Status breakdown for this group", "allOf": [ { "$ref": "#/components/schemas/StatusBreakdownDto" } ] } }, "required": [ "value", "count", "byStatus" ] }, "GroupStatsByLabelResponseDto": { "type": "object", "properties": { "labelKey": { "type": "string", "description": "The label key used for grouping", "example": "environment" }, "groups": { "description": "Statistics for each label value", "type": "array", "items": { "$ref": "#/components/schemas/LabelGroupDto" } }, "total": { "type": "number", "description": "Total number of devices across all groups", "example": 53 } }, "required": [ "labelKey", "groups", "total" ] }, "GroupStatsResponseDto": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching devices", "example": 25 }, "byStatus": { "description": "Status breakdown of matching devices", "allOf": [ { "$ref": "#/components/schemas/StatusBreakdownDto" } ] }, "labelSelector": { "type": "object", "description": "The label selector used for filtering", "example": { "environment": "production" }, "additionalProperties": { "type": "string" } } }, "required": [ "total", "byStatus" ] }, "AddLabelToGroupDto": { "type": "object", "properties": { "labelSelector": { "type": "object", "description": "Label selector to match devices", "example": { "environment": "production", "region": "us-west" }, "additionalProperties": { "type": "string" } }, "key": { "type": "string", "description": "Label key to add", "example": "tier" }, "value": { "type": "string", "description": "Label value to add", "example": "edge" } }, "required": [ "labelSelector", "key", "value" ] }, "BulkOperationResponseDto": { "type": "object", "properties": { "affected": { "type": "number", "description": "Number of devices affected by the operation", "example": 15 }, "deviceIds": { "description": "IDs of affected devices", "example": [ "550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440001" ], "type": "array", "items": { "type": "string" } } }, "required": [ "affected", "deviceIds" ] }, "RemoveLabelFromGroupDto": { "type": "object", "properties": { "labelSelector": { "type": "object", "description": "Label selector to match devices", "example": { "environment": "production", "region": "us-west" }, "additionalProperties": { "type": "string" } }, "key": { "type": "string", "description": "Label key to remove", "example": "tier" } }, "required": [ "labelSelector", "key" ] }, "BulkUpdateLabelsDto": { "type": "object", "properties": { "labelSelector": { "type": "object", "description": "Label selector to match devices", "example": { "environment": "staging" }, "additionalProperties": { "type": "string" } }, "labels": { "type": "object", "description": "Labels to add or update on matching devices", "example": { "tier": "production", "version": "v2.0" }, "additionalProperties": { "type": "string" } } }, "required": [ "labelSelector", "labels" ] }, "BulkDeleteGroupDto": { "type": "object", "properties": { "labelSelector": { "type": "object", "description": "Label selector to match devices for deletion", "example": { "environment": "development", "status": "deprecated" }, "additionalProperties": { "type": "string" } } }, "required": [ "labelSelector" ] }, "BulkDeleteResponseDto": { "type": "object", "properties": { "deleted": { "type": "number", "description": "Number of devices deleted", "example": 5 }, "deviceIds": { "description": "IDs of deleted devices", "example": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "deviceIds" ] }, "CreateOrganizationDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization display name", "minLength": 2, "maxLength": 100, "example": "Acme Corporation" }, "slug": { "type": "string", "description": "Unique URL-friendly identifier (lowercase alphanumeric with hyphens)", "minLength": 2, "maxLength": 50, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "example": "acme-corp" }, "description": { "type": "string", "description": "Organization description", "maxLength": 500, "example": "Leading manufacturer of industrial automation equipment" }, "settings": { "type": "object", "description": "Organization-specific settings", "additionalProperties": true, "example": { "timezone": "America/New_York", "locale": "en-US" } }, "branding": { "type": "object", "description": "Organization branding configuration", "additionalProperties": true, "example": { "primaryColor": "#003366", "logo": "https://example.com/logo.png" } }, "primaryContact": { "type": "string", "description": "Primary contact name for the organization", "maxLength": 200, "example": "John Smith" }, "billingEmail": { "type": "string", "description": "Billing email address for the organization", "format": "email", "example": "billing@acme-corp.com" } }, "required": [ "name", "slug" ] }, "OrganizationStatsDto": { "type": "object", "properties": { "userCount": { "type": "number", "description": "Total number of users in the organization", "example": 25 }, "activeUsers": { "type": "number", "description": "Number of active users in the organization", "example": 20 }, "deviceCount": { "type": "number", "description": "Total number of devices in the organization", "example": 150 }, "activeDevices": { "type": "number", "description": "Number of online or provisioned devices", "example": 120 }, "deploymentCount": { "type": "number", "description": "Total number of deployments in the organization", "example": 42 }, "runningDeployments": { "type": "number", "description": "Number of running deployments", "example": 35 } }, "required": [ "userCount", "activeUsers", "deviceCount", "activeDevices", "deploymentCount", "runningDeployments" ] }, "OrganizationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique organization identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Organization display name", "example": "Acme Corporation" }, "slug": { "type": "string", "description": "Unique URL-friendly identifier", "example": "acme-corp" }, "description": { "type": "string", "description": "Organization description", "example": "Leading manufacturer of industrial automation equipment" }, "settings": { "type": "object", "description": "Organization-specific settings", "additionalProperties": true, "example": { "timezone": "America/New_York", "locale": "en-US" } }, "branding": { "type": "object", "description": "Organization branding configuration", "additionalProperties": true, "example": { "primaryColor": "#003366", "logo": "https://example.com/logo.png" } }, "status": { "type": "string", "description": "Organization status", "enum": [ "active", "suspended", "pending", "disabled" ], "example": "active" }, "lastActivityAt": { "format": "date-time", "type": "string", "description": "Last activity timestamp", "example": "2024-06-20T14:45:00Z", "nullable": true }, "primaryContact": { "type": "string", "description": "Primary contact name", "example": "John Smith", "nullable": true }, "billingEmail": { "type": "string", "description": "Billing email address", "format": "email", "example": "billing@acme-corp.com", "nullable": true }, "active": { "type": "boolean", "description": "Whether the organization is active (deprecated, use status)", "example": true, "deprecated": true }, "createdAt": { "format": "date-time", "type": "string", "description": "When the organization was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the organization was last updated", "example": "2024-06-20T14:45:00Z" }, "stats": { "description": "Organization resource statistics", "allOf": [ { "$ref": "#/components/schemas/OrganizationStatsDto" } ] } }, "required": [ "id", "name", "slug", "settings", "branding", "status", "active", "createdAt", "updatedAt" ] }, "OrganizationListResponseDto": { "type": "object", "properties": { "items": { "description": "List of organizations", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponseDto" } }, "total": { "type": "number", "description": "Total number of organizations matching the query", "example": 100 }, "limit": { "type": "number", "description": "Number of results returned", "example": 50 }, "offset": { "type": "number", "description": "Number of results skipped", "example": 0 } }, "required": [ "items", "total", "limit", "offset" ] }, "OrganizationStatusCountsDto": { "type": "object", "properties": { "active": { "type": "number", "description": "Number of active organizations", "example": 10 }, "suspended": { "type": "number", "description": "Number of suspended organizations", "example": 2 }, "pending": { "type": "number", "description": "Number of pending organizations", "example": 3 }, "disabled": { "type": "number", "description": "Number of disabled organizations", "example": 1 } }, "required": [ "active", "suspended", "pending", "disabled" ] }, "OrganizationAggregateStatsDto": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of organizations", "example": 16 }, "byStatus": { "description": "Organization counts grouped by status", "allOf": [ { "$ref": "#/components/schemas/OrganizationStatusCountsDto" } ] } }, "required": [ "total", "byStatus" ] }, "BulkDeleteOrganizationsResultDto": { "type": "object", "properties": { "deleted": { "type": "number", "description": "Number of organizations successfully purged" }, "errors": { "description": "Per-organization error messages for any that could not be purged (e.g. the active tenant, which is always skipped)", "type": "array", "items": { "type": "string" } }, "devices": { "type": "number", "description": "Total devices soft-deleted across all purged organizations" }, "deployments": { "type": "number", "description": "Total deployments soft-deleted (cancelled) across all purged organizations" }, "applications": { "type": "number", "description": "Total application packages soft-deleted across all purged organizations" } }, "required": [ "deleted", "errors", "devices", "deployments", "applications" ] }, "OrganizationWithStatsDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique organization identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Organization display name", "example": "Acme Corporation" }, "slug": { "type": "string", "description": "Unique URL-friendly identifier", "example": "acme-corp" }, "description": { "type": "string", "description": "Organization description", "example": "Leading manufacturer of industrial automation equipment" }, "settings": { "type": "object", "description": "Organization-specific settings", "additionalProperties": true, "example": { "timezone": "America/New_York", "locale": "en-US" } }, "branding": { "type": "object", "description": "Organization branding configuration", "additionalProperties": true, "example": { "primaryColor": "#003366", "logo": "https://example.com/logo.png" } }, "status": { "type": "string", "description": "Organization status", "enum": [ "active", "suspended", "pending", "disabled" ], "example": "active" }, "lastActivityAt": { "format": "date-time", "type": "string", "description": "Last activity timestamp", "example": "2024-06-20T14:45:00Z", "nullable": true }, "primaryContact": { "type": "string", "description": "Primary contact name", "example": "John Smith", "nullable": true }, "billingEmail": { "type": "string", "description": "Billing email address", "format": "email", "example": "billing@acme-corp.com", "nullable": true }, "active": { "type": "boolean", "description": "Whether the organization is active (deprecated, use status)", "example": true, "deprecated": true }, "createdAt": { "format": "date-time", "type": "string", "description": "When the organization was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the organization was last updated", "example": "2024-06-20T14:45:00Z" }, "stats": { "description": "Organization resource statistics", "allOf": [ { "$ref": "#/components/schemas/OrganizationStatsDto" } ] }, "userCount": { "type": "number", "description": "Total number of users in the organization", "example": 25 }, "activeUsers": { "type": "number", "description": "Number of active users in the organization", "example": 20 }, "deviceCount": { "type": "number", "description": "Total number of devices in the organization", "example": 150 }, "activeDevices": { "type": "number", "description": "Number of online or provisioned devices", "example": 120 }, "deploymentCount": { "type": "number", "description": "Total number of deployments in the organization", "example": 42 }, "runningDeployments": { "type": "number", "description": "Number of running deployments", "example": 35 } }, "required": [ "id", "name", "slug", "settings", "branding", "status", "active", "createdAt", "updatedAt", "userCount", "activeUsers", "deviceCount", "activeDevices", "deploymentCount", "runningDeployments" ] }, "UpdateOrganizationDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization display name", "minLength": 2, "maxLength": 100, "example": "Acme Corporation Inc." }, "description": { "type": "string", "description": "Organization description", "maxLength": 500, "example": "Updated description for the organization" }, "settings": { "type": "object", "description": "Organization-specific settings", "additionalProperties": true, "example": { "timezone": "Europe/London", "locale": "en-GB" } }, "branding": { "type": "object", "description": "Organization branding configuration", "additionalProperties": true, "example": { "primaryColor": "#006633", "logo": "https://example.com/new-logo.png" } }, "active": { "type": "boolean", "description": "Whether the organization is active (deprecated, use dedicated endpoints)", "example": true, "deprecated": true }, "primaryContact": { "type": "string", "description": "Primary contact name for the organization", "maxLength": 200, "example": "John Smith" }, "billingEmail": { "type": "string", "description": "Billing email address for the organization", "format": "email", "example": "billing@acme-corp.com" } } }, "ForceDeleteResultDto": { "type": "object", "properties": { "removedMemberships": { "type": "number", "description": "Number of OrganizationUser memberships removed from this tenant" }, "deletedUsers": { "type": "number", "description": "Number of users hard-deleted because the deleted tenant was their only membership" }, "switchedUsers": { "type": "number", "description": "Number of users that kept their account because they belong to at least one other tenant" }, "deletedDevices": { "type": "number", "description": "Number of devices soft-deleted as part of the cascade" }, "cancelledDeployments": { "type": "number", "description": "Number of deployments soft-deleted (cancelled) as part of the cascade" }, "deletedApplications": { "type": "number", "description": "Number of application packages soft-deleted as part of the cascade" } }, "required": [ "removedMemberships", "deletedUsers", "switchedUsers", "deletedDevices", "cancelledDeployments", "deletedApplications" ] }, "EnableOrganizationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for enabling the organization" } } }, "DisableOrganizationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for disabling the organization" } } }, "SuspendOrganizationDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for suspending the organization", "maxLength": 500, "example": "Payment overdue - account suspended pending resolution" } } }, "RenameOrganizationDto": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the organization" }, "slug": { "type": "string", "description": "New slug for the organization (optional, auto-generated from name if not provided)" } }, "required": [ "name" ] }, "DeletionBlocker": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of blocker", "enum": [ "users", "devices", "deployments", "applications" ] }, "count": { "type": "number", "description": "Count of resources blocking deletion" }, "message": { "type": "string", "description": "Human-readable message" } }, "required": [ "type", "count", "message" ] }, "DeletionCheckResponseDto": { "type": "object", "properties": { "canDelete": { "type": "boolean", "description": "Whether the organization can be deleted" }, "blockers": { "description": "List of blockers preventing deletion", "type": "array", "items": { "$ref": "#/components/schemas/DeletionBlocker" } } }, "required": [ "canDelete", "blockers" ] }, "OrganizationBulkOperationDto": { "type": "object", "properties": { "userIds": { "description": "User IDs to apply the action to", "example": [ "uuid1", "uuid2" ], "type": "array", "items": { "type": "string" } }, "action": { "type": "string", "description": "Action to perform", "enum": [ "enable_users", "disable_users", "remove_users" ] }, "reason": { "type": "string", "description": "Reason for the operation" } }, "required": [ "userIds", "action" ] }, "OrganizationBulkOperationResultDto": { "type": "object", "properties": { "processed": { "type": "number", "description": "Total number of users processed" }, "successful": { "type": "number", "description": "Number of successful operations" }, "failed": { "type": "number", "description": "Number of failed operations" }, "errors": { "type": "object", "description": "Failed user IDs with error messages", "additionalProperties": { "type": "string" } } }, "required": [ "processed", "successful", "failed" ] }, "ResetPasswordDto": { "type": "object", "properties": { "delivery": { "type": "string", "description": "How the reset reaches the user (FM-862). 'email' (the default) is non-destructive: the existing password keeps working and the user sets a new one from the emailed reset form. 'display' is the no-SMTP / air-gap recovery path only: it rotates the credential and returns the generated value once.", "enum": [ "email", "display" ], "default": "email" }, "password": { "type": "string", "description": "New password. Only honoured for delivery='display'; ignored for delivery='email', where only the user may set the password. If omitted for 'display', a random password is generated and returned once." }, "sendEmail": { "type": "boolean", "description": "DEPRECATED (FM-862): ignored. Use `delivery` instead — email delivery is now the default and is non-destructive.", "deprecated": true }, "reason": { "type": "string", "description": "Reason for resetting the password" } } }, "PasswordResetResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the password reset itself succeeded" }, "delivery": { "type": "string", "description": "The delivery mode that was applied.", "enum": [ "email", "display" ] }, "temporaryPassword": { "type": "string", "description": "One-time generated password. Present ONLY for delivery='display' when no explicit password was supplied. It is never stored and cannot be retrieved again — the caller must show it to the admin once. Absent for delivery='email', which never rotates the credential." }, "mustChangePassword": { "type": "boolean", "description": "User must change password on next login" }, "emailSent": { "type": "boolean", "description": "Whether a reset email was actually sent. False when the user has no linked Keycloak account, Keycloak sync is disabled, or the send failed (FM-602 S2)." }, "emailError": { "type": "string", "description": "Why the email was not sent, when emailSent is false (e.g. 'no-keycloak-account', 'keycloak-sync-disabled', 'keycloak-send-failed')." } }, "required": [ "success", "delivery", "mustChangePassword" ] }, "CreateUserDto": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address", "format": "email", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "User display name", "minLength": 2, "maxLength": 100, "example": "John Doe" }, "password": { "type": "string", "description": "User password (min 8 characters)", "minLength": 8, "format": "password", "example": "securePassword123!" }, "isSuperAdmin": { "type": "boolean", "description": "Whether the user is a super admin with platform-wide privileges", "default": false, "example": false }, "organizationId": { "type": "string", "description": "Organization ID to assign the user to upon creation", "format": "uuid" }, "roleId": { "type": "string", "description": "Role ID to assign to the user in the organization (defaults to viewer)", "format": "uuid" } }, "required": [ "email", "name" ] }, "UserResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "type": "string", "description": "User email address", "format": "email", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "User display name", "example": "John Doe" }, "active": { "type": "boolean", "description": "Whether the user account is active", "example": true }, "emailVerified": { "type": "boolean", "description": "Whether the user email has been verified", "example": true }, "isSuperAdmin": { "type": "boolean", "description": "Whether the user is a super admin with platform-wide privileges", "example": false }, "createdAt": { "format": "date-time", "type": "string", "description": "When the user was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the user was last updated", "example": "2024-06-20T14:45:00Z" }, "lastLoginAt": { "format": "date-time", "type": "string", "description": "When the user last logged in", "example": "2024-12-20T09:15:00Z" }, "identityProvider": { "type": "string", "description": "FM-1069: the Keycloak identity-provider alias the user last authenticated through (e.g. the Entra broker alias), or null for a local realm login.", "example": "entra" }, "isFederated": { "type": "boolean", "description": "FM-1069: whether the user authenticates through an external identity provider (federated). The UI hides the password-reset action when true, since federated users have no local password to reset.", "example": false }, "pendingEmailVerification": { "type": "boolean", "description": "True when this account cannot sign in to its organizations because its e-mail address is unverified AND it is not yet bound to a Keycloak identity. Both conditions matter: an unverified address only blocks the e-mail-keyed binding (FM-837), which is never attempted for an account that is already bound. An already-bound account with an unverified address signs in perfectly well, so flagging it would be a false alarm.", "example": false } }, "required": [ "id", "email", "active", "emailVerified", "isSuperAdmin", "createdAt", "updatedAt", "isFederated", "pendingEmailVerification" ] }, "UserListResponseDto": { "type": "object", "properties": { "items": { "description": "List of users", "type": "array", "items": { "$ref": "#/components/schemas/UserResponseDto" } }, "total": { "type": "number", "description": "Total number of users matching the query", "example": 100 }, "limit": { "type": "number", "description": "Number of results returned", "example": 50 }, "offset": { "type": "number", "description": "Number of results skipped", "example": 0 } }, "required": [ "items", "total", "limit", "offset" ] }, "UserStatusCountsDto": { "type": "object", "properties": { "active": { "type": "number", "description": "Number of active users", "example": 20 }, "inactive": { "type": "number", "description": "Number of inactive/disabled users", "example": 3 } }, "required": [ "active", "inactive" ] }, "UserAggregateStatsDto": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of users", "example": 25 }, "byStatus": { "description": "User counts by status", "allOf": [ { "$ref": "#/components/schemas/UserStatusCountsDto" } ] }, "byRole": { "type": "object", "description": "Organization-membership counts keyed by role name. Roles are organization-scoped, so the keys are whatever roles exist. Org-scoped this equals a user count; platform-wide a user in several organizations is counted once per membership.", "additionalProperties": { "type": "integer" }, "example": { "admin": 3, "operator": 8, "viewer": 14 } }, "pendingInvitations": { "type": "number", "description": "Number of invitations that are neither accepted nor expired. These are not users and are deliberately not part of byStatus.", "example": 2 } }, "required": [ "total", "byStatus", "byRole", "pendingInvitations" ] }, "OrganizationMembershipDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization UUID", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "organizationName": { "type": "string", "description": "Organization display name", "example": "Acme Corporation" }, "organizationSlug": { "type": "string", "description": "Organization URL-friendly slug", "example": "acme-corp" }, "roleId": { "type": "string", "description": "Role UUID", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "roleName": { "type": "string", "description": "Role display name", "example": "Administrator" }, "permissions": { "description": "List of permissions granted by this role", "example": [ "devices:read", "devices:write", "deployments:read" ], "type": "array", "items": { "type": "string" } } }, "required": [ "organizationId", "organizationName", "organizationSlug", "roleId", "roleName", "permissions" ] }, "UserWithOrganizationsDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique user identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "type": "string", "description": "User email address", "format": "email", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "User display name", "example": "John Doe" }, "active": { "type": "boolean", "description": "Whether the user account is active", "example": true }, "emailVerified": { "type": "boolean", "description": "Whether the user email has been verified", "example": true }, "isSuperAdmin": { "type": "boolean", "description": "Whether the user is a super admin with platform-wide privileges", "example": false }, "createdAt": { "format": "date-time", "type": "string", "description": "When the user was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the user was last updated", "example": "2024-06-20T14:45:00Z" }, "lastLoginAt": { "format": "date-time", "type": "string", "description": "When the user last logged in", "example": "2024-12-20T09:15:00Z" }, "identityProvider": { "type": "string", "description": "FM-1069: the Keycloak identity-provider alias the user last authenticated through (e.g. the Entra broker alias), or null for a local realm login.", "example": "entra" }, "isFederated": { "type": "boolean", "description": "FM-1069: whether the user authenticates through an external identity provider (federated). The UI hides the password-reset action when true, since federated users have no local password to reset.", "example": false }, "pendingEmailVerification": { "type": "boolean", "description": "True when this account cannot sign in to its organizations because its e-mail address is unverified AND it is not yet bound to a Keycloak identity. Both conditions matter: an unverified address only blocks the e-mail-keyed binding (FM-837), which is never attempted for an account that is already bound. An already-bound account with an unverified address signs in perfectly well, so flagging it would be a false alarm.", "example": false }, "organizations": { "description": "List of organizations the user belongs to", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMembershipDto" } } }, "required": [ "id", "email", "active", "emailVerified", "isSuperAdmin", "createdAt", "updatedAt", "isFederated", "pendingEmailVerification", "organizations" ] }, "UpdateUserDto": { "type": "object", "properties": { "name": { "type": "string", "description": "User display name", "minLength": 2, "maxLength": 100, "example": "John Smith" }, "active": { "type": "boolean", "description": "Whether the user account is active", "example": true }, "emailVerified": { "type": "boolean", "description": "Whether the user email has been verified", "example": true } } }, "AddUserToOrganizationDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization UUID to add the user to", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "roleId": { "type": "string", "description": "Role UUID to assign to the user in the organization", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "required": [ "organizationId", "roleId" ] }, "ResendVerificationResponseDto": { "type": "object", "properties": { "sent": { "type": "boolean", "description": "Whether Keycloak accepted the request to send the message. False means the user is still flagged to verify at next sign-in, but no e-mail was delivered.", "example": true }, "email": { "type": "string", "description": "The address the message was sent to.", "example": "user@example.com" }, "error": { "type": "string", "description": "Why the send failed, when it did. Absent on success.", "example": "SMTP server not configured for this realm" } }, "required": [ "sent", "email" ] }, "UpdateUserRoleDto": { "type": "object", "properties": { "roleId": { "type": "string", "description": "New role UUID to assign to the user", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "required": [ "roleId" ] }, "EnableUserDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for enabling the user" } } }, "DisableUserDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for disabling the user" } } }, "BulkOperationDto": { "type": "object", "properties": { "userIds": { "description": "User IDs to apply the action to", "example": [ "uuid1", "uuid2" ], "type": "array", "items": { "type": "string" } }, "action": { "type": "string", "description": "Action to perform", "enum": [ "enable", "disable", "delete", "reset_password", "assign_role" ] }, "roleId": { "type": "string", "description": "Role ID for assign_role action" }, "organizationId": { "type": "string", "description": "Organization ID for assign_role action" }, "reason": { "type": "string", "description": "Reason for the operation" } }, "required": [ "userIds", "action" ] }, "BulkUserOutcomeDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "Target user ID" }, "success": { "type": "boolean", "description": "Whether the operation fully succeeded for this user" }, "emailSent": { "type": "boolean", "description": "For reset_password: whether the reset email was actually delivered. False means the target was NOT counted as successful." }, "error": { "type": "string", "description": "Failure reason when success is false" } }, "required": [ "userId", "success" ] }, "BulkOperationResultDto": { "type": "object", "properties": { "processed": { "type": "number", "description": "Total number of users processed" }, "successful": { "type": "number", "description": "Number of successful operations" }, "failed": { "type": "number", "description": "Number of failed operations" }, "errors": { "type": "object", "description": "Failed user IDs with error messages", "additionalProperties": { "type": "string" } }, "outcomes": { "description": "Per-user outcome (FM-862). Populated for reset_password, where an undelivered reset is NOT counted as successful and carries emailSent=false.", "type": "array", "items": { "$ref": "#/components/schemas/BulkUserOutcomeDto" } } }, "required": [ "processed", "successful", "failed" ] }, "ExportUsersDto": { "type": "object", "properties": { "format": { "type": "string", "description": "Export format", "enum": [ "csv", "json" ], "default": "csv" }, "organizationId": { "type": "string", "description": "Filter by organization ID" }, "active": { "type": "boolean", "description": "Filter by active status" }, "userIds": { "description": "Specific user IDs to export", "type": "array", "items": { "type": "string" } } } }, "UserProfileDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "name": { "type": "string", "description": "User display name" }, "phone": { "type": "string", "description": "Phone number" }, "timezone": { "type": "string", "description": "Timezone", "default": "UTC" }, "locale": { "type": "string", "description": "Locale", "default": "en" }, "emailNotifications": { "type": "boolean", "description": "Email notifications enabled", "default": true }, "smsNotifications": { "type": "boolean", "description": "SMS notifications enabled", "default": false }, "pushNotifications": { "type": "boolean", "description": "Push notifications enabled", "default": true }, "marketingEmails": { "type": "boolean", "description": "Marketing emails enabled", "default": false }, "bio": { "type": "string", "description": "User bio" }, "jobTitle": { "type": "string", "description": "Job title" }, "department": { "type": "string", "description": "Department" }, "location": { "type": "string", "description": "Location" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at" }, "lastLoginAt": { "format": "date-time", "type": "string", "description": "Last login timestamp" }, "isSuperAdmin": { "type": "boolean", "description": "Whether the user is a super admin", "default": false }, "roles": { "description": "Effective roles for the current user", "example": [ "admin" ], "type": "array", "items": { "type": "string" } }, "isEntraFederationEnabled": { "type": "boolean", "description": "Whether the realm has Entra federation enabled (FM-1087). When true, manual role changes, invites, password resets, user creation and superadmin grant/revoke are governed by Entra mappings instead.", "default": false }, "isFederated": { "type": "boolean", "description": "Whether the CURRENT session user is federated (has a linked external identity provider, e.g. Entra). Derived from the users.identityProvider column (FM-1087). Used together with isEntraFederationEnabled to warn a non-federated user signed in on an Entra-enabled realm.", "default": false } }, "required": [ "id", "email", "timezone", "locale", "emailNotifications", "smsNotifications", "pushNotifications", "marketingEmails", "createdAt", "updatedAt", "isSuperAdmin", "roles", "isEntraFederationEnabled", "isFederated" ] }, "UpdateProfileDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name" }, "phone": { "type": "string", "description": "Phone number" }, "timezone": { "type": "string", "description": "Timezone" }, "locale": { "type": "string", "description": "Locale" }, "bio": { "type": "string", "description": "Bio" }, "jobTitle": { "type": "string", "description": "Job title" }, "department": { "type": "string", "description": "Department" }, "location": { "type": "string", "description": "Location" } } }, "UpdateNotificationPreferencesDto": { "type": "object", "properties": { "emailNotifications": { "type": "boolean", "description": "Email notifications enabled" }, "smsNotifications": { "type": "boolean", "description": "SMS notifications enabled" }, "pushNotifications": { "type": "boolean", "description": "Push notifications enabled" }, "marketingEmails": { "type": "boolean", "description": "Marketing emails enabled" } } }, "ChangePasswordDto": { "type": "object", "properties": { "currentPassword": { "type": "string", "description": "Current password" }, "newPassword": { "type": "string", "description": "New password" } }, "required": [ "currentPassword", "newPassword" ] }, "UserSessionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Session ID" }, "ipAddress": { "type": "string", "description": "IP address" }, "userAgent": { "type": "string", "description": "User agent" }, "deviceType": { "type": "string", "description": "Device type" }, "browser": { "type": "string", "description": "Browser" }, "operatingSystem": { "type": "string", "description": "Operating system" }, "location": { "type": "string", "description": "Location" }, "startedAt": { "format": "date-time", "type": "string", "description": "Session started at" }, "lastActivityAt": { "format": "date-time", "type": "string", "description": "Last activity at" }, "expiresAt": { "format": "date-time", "type": "string", "description": "Session expires at" }, "isCurrent": { "type": "boolean", "description": "Is current session" }, "isActive": { "type": "boolean", "description": "Is active (not terminated or expired)" } }, "required": [ "id", "ipAddress", "startedAt", "lastActivityAt", "expiresAt", "isCurrent", "isActive" ] }, "SessionListResponseDto": { "type": "object", "properties": { "items": { "description": "Sessions", "type": "array", "items": { "$ref": "#/components/schemas/UserSessionDto" } }, "total": { "type": "number", "description": "Total count" } }, "required": [ "items", "total" ] }, "UserActivityDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity ID" }, "activityType": { "type": "string", "description": "Activity type" }, "ipAddress": { "type": "string", "description": "IP address" }, "description": { "type": "string", "description": "Description" }, "success": { "type": "boolean", "description": "Success status" }, "errorMessage": { "type": "string", "description": "Error message" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "metadata": { "type": "object", "description": "Metadata" } }, "required": [ "id", "activityType", "success", "createdAt" ] }, "ActivityListResponseDto": { "type": "object", "properties": { "items": { "description": "Activities", "type": "array", "items": { "$ref": "#/components/schemas/UserActivityDto" } }, "total": { "type": "number", "description": "Total count" }, "limit": { "type": "number", "description": "Limit" }, "offset": { "type": "number", "description": "Offset" } }, "required": [ "items", "total", "limit", "offset" ] }, "CreateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the API key", "example": "Production CI/CD Key", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "description": "Description of the API key purpose", "example": "Used by GitHub Actions for automated deployments", "maxLength": 500 }, "permissions": { "description": "List of permission keys to grant to this API key", "example": [ "devices:read", "deployments:read", "deployments:write" ], "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "description": "Expiration date for the API key in ISO 8601 format", "format": "date-time", "example": "2025-12-31T23:59:59Z" } }, "required": [ "name" ] }, "ApiKeyCreatedResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique API key identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Display name for the API key", "example": "Production CI/CD Key" }, "description": { "type": "string", "description": "Description of the API key purpose", "example": "Used by GitHub Actions for automated deployments" }, "keyPrefix": { "type": "string", "description": "Prefix of the API key for identification (first 8 characters)", "example": "mwfm_abc" }, "permissions": { "description": "List of permission keys granted to this API key", "example": [ "devices:read", "deployments:read", "deployments:write" ], "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "format": "date-time", "type": "string", "description": "When the API key was last used", "example": "2024-06-20T14:45:00Z" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the API key expires", "example": "2025-12-31T23:59:59Z" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the API key was created", "example": "2024-01-15T10:30:00Z" }, "createdBy": { "type": "string", "description": "User ID who created this API key", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "key": { "type": "string", "description": "Full API key value. Only returned on creation - store securely as it cannot be retrieved again.", "example": "mwfm_abc123def456ghi789jkl012mno345pqr" } }, "required": [ "id", "name", "keyPrefix", "permissions", "createdAt", "key" ] }, "ApiKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique API key identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Display name for the API key", "example": "Production CI/CD Key" }, "description": { "type": "string", "description": "Description of the API key purpose", "example": "Used by GitHub Actions for automated deployments" }, "keyPrefix": { "type": "string", "description": "Prefix of the API key for identification (first 8 characters)", "example": "mwfm_abc" }, "permissions": { "description": "List of permission keys granted to this API key", "example": [ "devices:read", "deployments:read", "deployments:write" ], "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "format": "date-time", "type": "string", "description": "When the API key was last used", "example": "2024-06-20T14:45:00Z" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the API key expires", "example": "2025-12-31T23:59:59Z" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the API key was created", "example": "2024-01-15T10:30:00Z" }, "createdBy": { "type": "string", "description": "User ID who created this API key", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" } }, "required": [ "id", "name", "keyPrefix", "permissions", "createdAt" ] }, "ApiKeyListResponseDto": { "type": "object", "properties": { "items": { "description": "List of API keys", "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponseDto" } }, "total": { "type": "number", "description": "Total number of API keys matching the query", "example": 5 }, "limit": { "type": "number", "description": "Number of results returned", "example": 20 }, "offset": { "type": "number", "description": "Number of results skipped", "example": 0 } }, "required": [ "items", "total", "limit", "offset" ] }, "UpdateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated display name for the API key", "example": "Production CI/CD Key v2", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "description": "Updated description of the API key purpose", "example": "Used by GitHub Actions and Jenkins for deployments", "maxLength": 500 }, "permissions": { "description": "Updated list of permission keys for this API key", "example": [ "devices:read", "devices:write", "deployments:read" ], "type": "array", "items": { "type": "string" } } } }, "CreateInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to send the invitation to", "format": "email", "example": "newuser@example.com" }, "roleId": { "type": "string", "description": "Role ID to assign to the user when they accept the invitation", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "expiresInDays": { "type": "number", "description": "Number of days until the invitation expires", "minimum": 1, "maximum": 30, "default": 7, "example": 7 }, "department": { "type": "string", "description": "Department to assign to the user when they accept the invitation", "example": "Engineering", "maxLength": 200 }, "personalMessage": { "type": "string", "description": "Personal message to include in the invitation email", "example": "Welcome to the team! Looking forward to working with you.", "maxLength": 1000 } }, "required": [ "email", "roleId" ] }, "InvitationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique invitation identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "type": "string", "description": "Email address the invitation was sent to", "format": "email", "example": "newuser@example.com" }, "roleId": { "type": "string", "description": "Role ID that will be assigned when the invitation is accepted", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "organizationId": { "type": "string", "description": "Organization ID the user will be added to", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "organizationName": { "type": "string", "description": "Name of the organization", "example": "Acme Corporation" }, "invitedById": { "type": "string", "description": "User ID who sent the invitation (null if inviter was deleted)", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440003" }, "invitedByEmail": { "type": "string", "description": "Email of the user who sent the invitation (null if inviter was deleted)", "format": "email", "example": "admin@acme.com" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the invitation expires", "example": "2024-06-27T10:30:00Z" }, "acceptedAt": { "format": "date-time", "type": "string", "description": "When the invitation was accepted (null if pending)", "example": "2024-06-21T14:45:00Z" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the invitation was created", "example": "2024-06-20T10:30:00Z" }, "isPending": { "type": "boolean", "description": "Whether the invitation is pending (not accepted)", "example": true }, "isExpired": { "type": "boolean", "description": "Whether the invitation has expired", "example": false } }, "required": [ "id", "email", "roleId", "organizationId", "organizationName", "expiresAt", "createdAt", "isPending", "isExpired" ] }, "InvitationListResponseDto": { "type": "object", "properties": { "items": { "description": "List of invitations", "type": "array", "items": { "$ref": "#/components/schemas/InvitationResponseDto" } }, "total": { "type": "number", "description": "Total number of invitations matching the query", "example": 5 } }, "required": [ "items", "total" ] }, "ResendInvitationDto": { "type": "object", "properties": { "expiresInDays": { "type": "number", "description": "Number of days until the invitation expires (resets the expiration)", "minimum": 1, "maximum": 30, "default": 7, "example": 7 } } }, "InvitationDetailsDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Invitation token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "email": { "type": "string", "description": "Email address the invitation was sent to", "format": "email", "example": "newuser@example.com" }, "organizationName": { "type": "string", "description": "Name of the organization being invited to", "example": "Acme Corporation" }, "organizationSlug": { "type": "string", "description": "URL-friendly slug of the organization", "example": "acme-corporation" }, "invitedByName": { "type": "string", "description": "Name of the user who sent the invitation", "example": "Admin User" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the invitation expires", "example": "2024-06-27T10:30:00Z" }, "userExists": { "type": "boolean", "description": "True when a user with this email already exists. The accept form should skip the password field in that case — credentials are preserved and the existing user is just added to the new tenant.", "example": false } }, "required": [ "token", "email", "organizationName", "organizationSlug", "expiresAt", "userExists" ] }, "AcceptInvitationDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Invitation token from the invitation email", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "name": { "type": "string", "description": "Display name for the new user (required if user does not exist)", "example": "John Doe", "minLength": 2, "maxLength": 100 }, "password": { "type": "string", "description": "Password for the new user (required if user does not exist)", "example": "SecureP@ssw0rd!", "minLength": 8, "maxLength": 128 } }, "required": [ "token" ] }, "PermissionDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Unique permission key", "example": "devices:write" }, "name": { "type": "string", "description": "Human-readable permission name", "example": "Write Devices" }, "description": { "type": "string", "description": "Permission description", "example": "Allows creating, updating, and deleting devices" }, "category": { "type": "string", "description": "Permission category for grouping", "example": "Devices" } }, "required": [ "key", "name", "description", "category" ] }, "PermissionListResponseDto": { "type": "object", "properties": { "permissions": { "description": "List of available permissions", "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } }, "required": [ "permissions" ] }, "RoleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique role identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Role display name", "example": "Device Operator" }, "description": { "type": "string", "description": "Role description", "example": "Can view and manage devices but not deployments" }, "permissions": { "description": "List of permission keys assigned to this role", "example": [ "devices:read", "devices:write", "deployments:read" ], "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean", "description": "Whether this is a system-defined role (cannot be modified)", "example": false }, "organizationId": { "type": "string", "description": "Organization ID (null for system roles)", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the role was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the role was last updated", "example": "2024-06-20T14:45:00Z" } }, "required": [ "id", "name", "permissions", "isSystem", "createdAt", "updatedAt" ] }, "RoleListResponseDto": { "type": "object", "properties": { "items": { "description": "List of roles", "type": "array", "items": { "$ref": "#/components/schemas/RoleResponseDto" } }, "total": { "type": "number", "description": "Total number of roles matching the query", "example": 10 }, "limit": { "type": "number", "description": "Number of results returned", "example": 10 }, "offset": { "type": "number", "description": "Number of results skipped", "example": 0 } }, "required": [ "items", "total", "limit", "offset" ] }, "CreateRoleDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Role display name", "minLength": 2, "maxLength": 50, "example": "Device Operator" }, "description": { "type": "string", "description": "Role description", "maxLength": 200, "example": "Can view and manage devices but not deployments" }, "permissions": { "description": "List of permission keys assigned to this role", "example": [ "devices:read", "devices:write", "deployments:read" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name", "permissions" ] }, "UpdateRoleDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Role display name", "minLength": 2, "maxLength": 50, "example": "Senior Device Operator" }, "description": { "type": "string", "description": "Role description", "maxLength": 200, "example": "Can view and manage devices and deployments" }, "permissions": { "description": "List of permission keys assigned to this role", "example": [ "devices:read", "devices:write", "deployments:read", "deployments:write" ], "type": "array", "items": { "type": "string" } } } }, "AuditLogResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique audit log identifier", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "actorType": { "type": "string", "enum": [ "USER", "API_KEY", "DEVICE", "SYSTEM" ], "description": "Actor type discriminator (FM-922 Phase 3).", "example": "USER" }, "userId": { "type": "string", "description": "User ID who performed the action", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "userName": { "type": "string", "description": "Display name of the user at the time of the action. Captured at write time so audit entries remain readable after the user is deleted.", "example": "Alice Admin" }, "apiKeyId": { "type": "string", "description": "API key ID used for the action", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440003" }, "apiKeyName": { "type": "string", "description": "Display name of the API key at the time of the action.", "example": "ci-publisher" }, "deviceId": { "type": "string", "description": "Internal Device.id (UUID) when actorType is DEVICE.", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440005" }, "deviceName": { "type": "string", "description": "Device.name captured at write time (survives device deletion).", "example": "Edge Gateway 1" }, "deviceClientId": { "type": "string", "description": "Margo clientId captured at write time.", "example": "781d48bf-5ff9-b574-d95e-8d8b557022d2" }, "action": { "type": "string", "description": "Type of action performed", "enum": [ "CREATE", "READ", "UPDATE", "DELETE", "LOGIN", "LOGOUT", "LOGIN_FAILED", "PERMISSION_GRANTED", "PERMISSION_DENIED", "EXPORT", "IMPORT", "BULK_UPDATE", "BULK_DELETE", "PASSWORD_CHANGE", "API_KEY_CREATED", "API_KEY_REVOKED", "CERTIFICATE_ISSUED", "CERTIFICATE_REVOKED", "DEPLOYMENT_STARTED", "DEPLOYMENT_COMPLETED", "DEPLOYMENT_FAILED", "DEPLOYMENT_ROLLED_BACK", "DEVICE_ONBOARDING_REJECTED", "DEVICE_CAPABILITY_REPORT_REJECTED", "DEVICE_STATUS_REPORT_REJECTED", "DEVICE_DESIRED_STATE_FETCH_REJECTED", "DEVICE_ONBOARDING_REJECTED_SUMMARY" ], "example": "CREATE" }, "entityType": { "type": "string", "description": "Entity type that was affected", "example": "Device" }, "entityId": { "type": "string", "description": "ID of the affected entity", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440004" }, "entityName": { "type": "string", "description": "Human-readable name of the affected entity", "example": "Production Gateway 1" }, "beforeState": { "type": "object", "description": "State of the entity before the change", "additionalProperties": true, "example": { "status": "OFFLINE", "name": "Old Name" } }, "afterState": { "type": "object", "description": "State of the entity after the change", "additionalProperties": true, "example": { "status": "ONLINE", "name": "New Name" } }, "changedFields": { "description": "List of fields that were changed", "example": [ "status", "name" ], "type": "array", "items": { "type": "string" } }, "ipAddress": { "type": "string", "description": "IP address of the client", "example": "192.168.1.100" }, "userAgent": { "type": "string", "description": "User agent of the client", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" }, "requestId": { "type": "string", "description": "Request correlation ID", "example": "req-123456" }, "sessionId": { "type": "string", "description": "Session ID", "example": "sess-789012" }, "success": { "type": "boolean", "description": "Whether the action was successful", "example": true }, "errorMessage": { "type": "string", "description": "Error message if action failed", "example": "Permission denied" }, "metadata": { "type": "object", "description": "Additional metadata", "additionalProperties": true, "example": { "source": "api", "version": "1.0" } }, "createdAt": { "format": "date-time", "type": "string", "description": "When the audit log was created", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organizationId", "action", "entityType", "changedFields", "success", "createdAt" ] }, "PaginationMeta": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching records", "example": 150 }, "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Number of records per page", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether more records are available", "example": true }, "nextCursor": { "type": "string", "description": "Cursor for next page", "example": "eyJpZCI6IjEyMzQifQ==" } }, "required": [ "total", "page", "limit", "hasMore" ] }, "AuditLogListResponseDto": { "type": "object", "properties": { "data": { "description": "List of audit log entries", "type": "array", "items": { "$ref": "#/components/schemas/AuditLogResponseDto" } }, "meta": { "description": "Pagination metadata", "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" } ] } }, "required": [ "data", "meta" ] }, "UserAuditCount": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "count": { "type": "number", "description": "Number of audit entries", "example": 42 } }, "required": [ "userId", "count" ] }, "AuditStatsResponseDto": { "type": "object", "properties": { "totalCount": { "type": "number", "description": "Total number of audit entries", "example": 1500 }, "byAction": { "type": "object", "description": "Count by action type", "additionalProperties": { "type": "number" }, "example": { "CREATE": 500, "UPDATE": 800, "DELETE": 200 } }, "byEntityType": { "type": "object", "description": "Count by entity type", "additionalProperties": { "type": "number" }, "example": { "Device": 900, "User": 400, "Organization": 200 } }, "byUser": { "description": "Top users by activity", "type": "array", "items": { "$ref": "#/components/schemas/UserAuditCount" } }, "successRate": { "type": "number", "description": "Success rate as a decimal (0-1)", "example": 0.95 } }, "required": [ "totalCount", "byAction", "byEntityType", "byUser", "successRate" ] }, "AuthEventDto": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "auth.login.success", "auth.login.failed", "auth.refresh.success", "auth.refresh.failed", "auth.logout", "auth.session_terminated_by_admin", "auth.federated_login.success", "auth.federated_login.failed" ], "description": "Canonical auth-audit event name (FM-494)." }, "success": { "type": "boolean", "description": "Whether the underlying auth operation succeeded." }, "provider": { "type": "string", "description": "OAuth/OIDC provider name when relevant (e.g. \"keycloak\", \"entra\")." }, "errorCode": { "type": "string", "description": "Short error code for failed events (e.g. \"expired_token\")." }, "errorDescription": { "type": "string", "description": "Human-readable error description for failed events." }, "metadata": { "type": "object", "description": "Free-form metadata (small JSON object). MUST NOT contain access tokens." } }, "required": [ "event", "success" ] }, "SystemRoleDto": { "type": "object", "properties": { "id": { "type": "string", "description": "System role record ID" }, "userId": { "type": "string", "description": "User ID who has this role" }, "userEmail": { "type": "string", "description": "User email" }, "userName": { "type": "string", "description": "User name" }, "role": { "type": "string", "enum": [ "SUPERUSER", "SUPPORT" ], "description": "Role type" }, "grantedAt": { "format": "date-time", "type": "string", "description": "When the role was granted" }, "grantedById": { "type": "string", "description": "User ID who granted the role (null if granter was deleted)" }, "grantedByEmail": { "type": "string", "description": "Email of user who granted the role (null if granter was deleted)" }, "reason": { "type": "string", "description": "Reason for granting" }, "revokedAt": { "format": "date-time", "type": "string", "description": "When the role was revoked (null if active)" }, "revokedById": { "type": "string", "description": "User ID who revoked the role" }, "revokedByEmail": { "type": "string", "description": "Email of user who revoked the role" }, "isActive": { "type": "boolean", "description": "Whether the role is currently active" } }, "required": [ "id", "userId", "userEmail", "role", "grantedAt", "isActive" ] }, "SystemRoleListResponseDto": { "type": "object", "properties": { "items": { "description": "List of system roles", "type": "array", "items": { "$ref": "#/components/schemas/SystemRoleDto" } }, "total": { "type": "number", "description": "Total count" }, "hasMore": { "type": "boolean", "description": "Whether there are more items" } }, "required": [ "items", "total", "hasMore" ] }, "UserSystemRolesDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID" }, "isSuperuser": { "type": "boolean", "description": "Whether user is a superuser" }, "isSupport": { "type": "boolean", "description": "Whether user has support role" }, "activeRoles": { "description": "Active system roles", "type": "array", "items": { "$ref": "#/components/schemas/SystemRoleDto" } } }, "required": [ "userId", "isSuperuser", "isSupport", "activeRoles" ] }, "GrantSystemRoleDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID to grant the role to" }, "role": { "type": "string", "enum": [ "SUPERUSER", "SUPPORT" ], "description": "Role type to grant" }, "reason": { "type": "string", "description": "Reason for granting the role" } }, "required": [ "userId", "role" ] }, "RevokeSystemRoleDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID to revoke the role from" }, "role": { "type": "string", "enum": [ "SUPERUSER", "SUPPORT" ], "description": "Role type to revoke" }, "reason": { "type": "string", "description": "Reason for revoking the role" } }, "required": [ "userId", "role" ] }, "TenantSwitchDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Switch record ID" }, "userId": { "type": "string", "description": "User ID who performed the switch" }, "fromOrgId": { "type": "string", "description": "Original organization ID" }, "fromOrgName": { "type": "string", "description": "Original organization name" }, "toOrgId": { "type": "string", "description": "Target organization ID" }, "toOrgName": { "type": "string", "description": "Target organization name" }, "duration": { "type": "string", "description": "Duration of the switch" }, "reason": { "type": "string", "description": "Reason for switching" }, "switchedAt": { "format": "date-time", "type": "string", "description": "When the switch was performed" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the switch expires" }, "returnedAt": { "format": "date-time", "type": "string", "description": "When the user returned to default tenant" }, "isActive": { "type": "boolean", "description": "Whether the switch is currently active" } }, "required": [ "id", "userId", "toOrgId", "switchedAt", "isActive" ] }, "TenantContextDto": { "type": "object", "properties": { "isSwitched": { "type": "boolean", "description": "Whether user is currently switched to another tenant" }, "originalOrgId": { "type": "string", "description": "Original organization ID (if switched)" }, "originalOrgName": { "type": "string", "description": "Original organization name (if switched)" }, "currentOrgId": { "type": "string", "description": "Current organization ID" }, "currentOrgName": { "type": "string", "description": "Current organization name" }, "currentOrgSlug": { "type": "string", "description": "Current organization slug" }, "originalOrgSlug": { "type": "string", "description": "Original organization slug (if switched)" }, "activeSwitch": { "description": "Active switch details (if switched)", "allOf": [ { "$ref": "#/components/schemas/TenantSwitchDto" } ] }, "expiresAt": { "format": "date-time", "type": "string", "description": "When the switch expires (if switched)" } }, "required": [ "isSwitched", "currentOrgId" ] }, "SwitchTenantDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Target organization ID to switch to" }, "duration": { "type": "string", "enum": [ "15m", "1h", "4h", "session" ], "description": "Duration of the switch", "default": "session" }, "reason": { "type": "string", "description": "Reason for the switch" } }, "required": [ "organizationId" ] }, "MyTenantSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "slug": { "type": "string", "description": "Organization slug" }, "roleName": { "type": "string", "description": "Role name (null for superuser/support)" }, "accessVia": { "type": "string", "description": "How the user has access: direct membership or via system role", "enum": [ "member", "system" ] }, "isDefault": { "type": "boolean", "description": "Whether this is the user's current/default organization" } }, "required": [ "id", "name", "slug", "accessVia", "isDefault" ] }, "MyTenantListDto": { "type": "object", "properties": { "items": { "description": "Tenants the user can access", "type": "array", "items": { "$ref": "#/components/schemas/MyTenantSummaryDto" } }, "total": { "type": "number", "description": "Total tenants" }, "isSystemView": { "type": "boolean", "description": "True when items reflect a system-role view (all orgs); false when items only contain memberships" } }, "required": [ "items", "total", "isSystemView" ] }, "TenantSwitchListResponseDto": { "type": "object", "properties": { "items": { "description": "List of tenant switches", "type": "array", "items": { "$ref": "#/components/schemas/TenantSwitchDto" } }, "total": { "type": "number", "description": "Total count" }, "hasMore": { "type": "boolean", "description": "Whether there are more items" } }, "required": [ "items", "total", "hasMore" ] }, "AdminActivityDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity ID" }, "user": { "type": "object", "description": "User who performed the activity" }, "targetUser": { "type": "object", "description": "Target user (if applicable)" }, "activityType": { "type": "string", "description": "Activity type" }, "organizationId": { "type": "string", "description": "Organization ID" }, "ipAddress": { "type": "string", "description": "IP address" }, "userAgent": { "type": "string", "description": "User agent" }, "description": { "type": "string", "description": "Description" }, "success": { "type": "boolean", "description": "Success status" }, "errorMessage": { "type": "string", "description": "Error message" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "metadata": { "type": "object", "description": "Metadata" } }, "required": [ "id", "user", "activityType", "success", "createdAt" ] }, "AdminActivityListResponseDto": { "type": "object", "properties": { "items": { "description": "Activities", "type": "array", "items": { "$ref": "#/components/schemas/AdminActivityDto" } }, "total": { "type": "number", "description": "Total count" }, "limit": { "type": "number", "description": "Limit" }, "offset": { "type": "number", "description": "Offset" } }, "required": [ "items", "total", "limit", "offset" ] }, "TenantActivitySummaryDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization ID" }, "organizationName": { "type": "string", "description": "Organization name" }, "totalActivities": { "type": "number", "description": "Total activities in period" }, "activeUsers": { "type": "number", "description": "Active users (users with activity)" }, "totalUsers": { "type": "number", "description": "Total users in organization" }, "lastActivityAt": { "format": "date-time", "type": "string", "description": "Last activity timestamp" }, "activityBreakdown": { "type": "object", "description": "Activity breakdown by type" }, "loginCount": { "type": "number", "description": "Login count in period" }, "failedLoginCount": { "type": "number", "description": "Failed login count in period" }, "daysSinceLastActivity": { "type": "number", "description": "Days since last activity" }, "isInactive": { "type": "boolean", "description": "Is inactive (no activity in threshold days)" } }, "required": [ "organizationId", "organizationName", "totalActivities", "activeUsers", "totalUsers", "activityBreakdown", "loginCount", "failedLoginCount", "daysSinceLastActivity", "isInactive" ] }, "InactivityReportDto": { "type": "object", "properties": { "thresholdDays": { "type": "number", "description": "Inactivity threshold in days" }, "generatedAt": { "format": "date-time", "type": "string", "description": "Report generated at" }, "inactiveTenants": { "description": "Inactive tenants", "type": "array", "items": { "$ref": "#/components/schemas/TenantActivitySummaryDto" } }, "totalInactiveTenants": { "type": "number", "description": "Total inactive tenants" }, "totalTenants": { "type": "number", "description": "Total tenants checked" } }, "required": [ "thresholdDays", "generatedAt", "inactiveTenants", "totalInactiveTenants", "totalTenants" ] }, "ExportActivityDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Filter by organization ID" }, "userId": { "type": "string", "description": "Filter by user ID" }, "startDate": { "type": "string", "description": "Filter by start date" }, "endDate": { "type": "string", "description": "Filter by end date" }, "activityTypes": { "description": "Filter by activity types", "type": "array", "items": { "type": "string" } }, "format": { "type": "string", "description": "Export format", "enum": [ "csv", "json" ], "default": "csv" }, "maxRecords": { "type": "number", "description": "Maximum number of records", "default": 10000 } } }, "CaCertificateResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique CA certificate identifier (UUID)", "example": "550e8400-e29b-41d4-a716-446655440000", "format": "uuid" }, "name": { "type": "string", "description": "Human-readable name for the CA certificate", "example": "Production Root CA" }, "fingerprint": { "type": "string", "description": "SHA-256 fingerprint of the certificate", "example": "A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2" }, "isRoot": { "type": "boolean", "description": "Whether this is a root CA certificate", "example": true }, "isDefault": { "type": "boolean", "description": "Whether this is the default signing CA", "example": true }, "notBefore": { "format": "date-time", "type": "string", "description": "Certificate validity start date", "example": "2024-01-01T00:00:00Z" }, "notAfter": { "format": "date-time", "type": "string", "description": "Certificate validity end date (expiration)", "example": "2034-01-01T00:00:00Z" }, "retiredAt": { "format": "date-time", "type": "string", "description": "Date when the CA certificate was retired", "example": "2024-06-01T00:00:00Z" }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the CA certificate was created", "example": "2024-01-01T00:00:00Z" }, "subject": { "type": "string", "description": "Full subject distinguished name", "example": "CN=Root CA, O=logiccloud, C=US" }, "issuer": { "type": "string", "description": "Full issuer distinguished name", "example": "CN=Root CA, O=logiccloud, C=US" }, "serialNumber": { "type": "string", "description": "Certificate serial number (hex)", "example": "01:AB:CD:EF" }, "keyAlgorithm": { "type": "string", "description": "Public key algorithm and size", "example": "RSA-4096" }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm", "example": "SHA256withRSA" }, "subjectAltNames": { "description": "Subject Alternative Names", "example": [ "DNS:example.com", "IP:192.168.1.1" ], "type": "array", "items": { "type": "string" } }, "certificate": { "type": "string", "description": "PEM-encoded public certificate (safe to share)", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } }, "required": [ "id", "name", "fingerprint", "isRoot", "isDefault", "notBefore", "notAfter", "createdAt" ] }, "CaCertificateListResponseDto": { "type": "object", "properties": { "data": { "description": "List of CA certificates", "type": "array", "items": { "$ref": "#/components/schemas/CaCertificateResponseDto" } }, "total": { "type": "number", "description": "Total number of CA certificates", "example": 5 }, "hasMore": { "type": "boolean", "description": "Whether there are more results available", "example": false }, "nextCursor": { "type": "string", "description": "Cursor for the next page of results", "example": "550e8400-e29b-41d4-a716-446655440001", "format": "uuid" } }, "required": [ "data", "total", "hasMore" ] }, "CreateCaCertificateDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the CA certificate", "example": "Production Root CA", "maxLength": 255 }, "certificate": { "type": "string", "description": "PEM-encoded CA certificate", "example": "-----BEGIN CERTIFICATE-----\nMIIBkTCC...\n-----END CERTIFICATE-----" }, "privateKey": { "type": "string", "description": "PEM-encoded private key (will be encrypted at rest)", "example": "-----BEGIN PRIVATE KEY-----\nMIIEvQIB...\n-----END PRIVATE KEY-----" }, "passphrase": { "type": "string", "description": "Passphrase for encrypted private keys (PKCS#8 or legacy PEM encryption)", "example": "my-secret-passphrase" }, "isRoot": { "type": "boolean", "description": "Whether this is a root CA certificate", "example": true, "default": false }, "isDefault": { "type": "boolean", "description": "Set as the default signing CA for new device certificates", "example": false, "default": false } }, "required": [ "name", "certificate", "privateKey" ] }, "GenerateCaCertificateDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the CA certificate", "example": "Development Root CA", "maxLength": 255 }, "commonName": { "type": "string", "description": "Common Name (CN) for the certificate subject", "example": "Fleet Manager Dev CA", "maxLength": 255 }, "organization": { "type": "string", "description": "Organization (O) for the certificate subject", "example": "logiccloud", "maxLength": 255 }, "country": { "type": "string", "description": "Country code (C) for the certificate subject (2-letter ISO 3166-1 alpha-2)", "example": "DE", "maxLength": 2 }, "validityYears": { "type": "number", "description": "Validity period in years (1-30)", "example": 10, "default": 10 }, "isDefault": { "type": "boolean", "description": "Set as the default signing CA for new device certificates", "example": false, "default": false } }, "required": [ "name", "commonName" ] }, "RenewCaCertificateDto": { "type": "object", "properties": { "validityDays": { "type": "number", "description": "Number of days to extend the certificate validity from today", "example": 365, "minimum": 1, "maximum": 3650, "default": 365 } } }, "CertificateListItemDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Certificate UUID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "type": { "type": "string", "description": "Certificate type", "enum": [ "device", "ca" ], "example": "device" }, "subject": { "type": "string", "description": "Certificate subject (Common Name)", "example": "CN=device-001.example.com" }, "issuer": { "type": "string", "description": "Certificate issuer", "example": "CN=Margo Root CA" }, "fingerprint": { "type": "string", "description": "Certificate SHA-256 fingerprint", "example": "A1:B2:C3:D4:E5:F6..." }, "notBefore": { "format": "date-time", "type": "string", "description": "Certificate validity start date", "example": "2024-01-01T00:00:00.000Z" }, "notAfter": { "format": "date-time", "type": "string", "description": "Certificate expiration date", "example": "2025-01-01T00:00:00.000Z" }, "status": { "type": "string", "description": "Certificate status", "enum": [ "valid", "expiring", "expired", "revoked" ], "example": "valid" }, "deviceId": { "type": "string", "description": "Device ID (only for device certificates)", "example": "550e8400-e29b-41d4-a716-446655440001" }, "deviceName": { "type": "string", "description": "Device name (only for device certificates)", "example": "Production Gateway 1" }, "createdAt": { "format": "date-time", "type": "string", "description": "Certificate creation date", "example": "2024-01-01T00:00:00.000Z" }, "serialNumber": { "type": "string", "description": "Certificate serial number (hex)" }, "keyAlgorithm": { "type": "string", "description": "Public key algorithm and size" }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm" }, "subjectAltNames": { "description": "Subject Alternative Names", "type": "array", "items": { "type": "string" } }, "certificate": { "type": "string", "description": "PEM-encoded public certificate (CA certs only)" } }, "required": [ "id", "type", "subject", "issuer", "fingerprint", "notBefore", "notAfter", "status", "createdAt" ] }, "CertificateListResponseDto": { "type": "object", "properties": { "data": { "description": "List of certificates", "type": "array", "items": { "$ref": "#/components/schemas/CertificateListItemDto" } }, "total": { "type": "number", "description": "Total number of certificates matching the filter", "example": 150 }, "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Number of items per page", "example": 20 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 8 } }, "required": [ "data", "total", "page", "limit", "totalPages" ] }, "CertificateStatsDto": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of certificates", "example": 150 }, "valid": { "type": "number", "description": "Number of valid certificates (not expiring within 30 days)", "example": 120 }, "expiring": { "type": "number", "description": "Number of certificates expiring within 30 days", "example": 15 }, "expired": { "type": "number", "description": "Number of expired certificates", "example": 5 }, "revoked": { "type": "number", "description": "Number of revoked certificates", "example": 10 } }, "required": [ "total", "valid", "expiring", "expired", "revoked" ] }, "CreateGitRegistryDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the registry within the organization", "example": "my-workloads-repo", "minLength": 2, "maxLength": 100 }, "url": { "type": "string", "description": "Git repository URL", "example": "https://github.com/org/workloads.git" }, "branch": { "type": "string", "description": "Branch to use", "example": "main", "default": "main" }, "path": { "type": "string", "description": "Path within the repository to scan for workloads", "example": "/workloads", "default": "/" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "HTTPS_TOKEN", "SSH_KEY" ], "default": "NONE", "example": "NONE" }, "credential": { "type": "string", "description": "Credential (token or SSH key) for authentication. Will be encrypted at rest.", "example": "ghp_xxxxxxxxxxxxxxxxxxxx" }, "syncIntervalMinutes": { "type": "number", "description": "Sync interval in minutes", "example": 60, "default": 60, "minimum": 1, "maximum": 1440 }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "default": true, "example": true } }, "required": [ "name", "url" ] }, "GitRegistryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "Organization ID that owns this registry", "example": "550e8400-e29b-41d4-a716-446655440001" }, "name": { "type": "string", "description": "Registry name", "example": "my-workloads-repo" }, "url": { "type": "string", "description": "Git repository URL", "example": "https://github.com/org/workloads.git" }, "branch": { "type": "string", "description": "Branch to use", "example": "main" }, "path": { "type": "string", "description": "Path within the repository to scan", "example": "/workloads" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "HTTPS_TOKEN", "SSH_KEY" ], "example": "NONE" }, "hasCredentials": { "type": "boolean", "description": "Whether credentials are configured", "example": false }, "syncIntervalMinutes": { "type": "number", "description": "Sync interval in minutes", "example": 60 }, "lastSyncAt": { "format": "date-time", "type": "string", "description": "Last successful sync timestamp", "example": "2024-01-15T10:30:00Z", "nullable": true }, "lastSyncError": { "type": "string", "description": "Last sync error message", "example": "Authentication failed", "nullable": true }, "lastSyncCommit": { "type": "string", "description": "Last synced commit SHA", "example": "abc123def456", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "example": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organizationId", "name", "url", "branch", "path", "authType", "hasCredentials", "syncIntervalMinutes", "enabled", "createdAt", "updatedAt" ] }, "GitRegistryListResponseDto": { "type": "object", "properties": { "items": { "description": "List of Git registries", "type": "array", "items": { "$ref": "#/components/schemas/GitRegistryResponseDto" } }, "total": { "type": "number", "description": "Total number of registries matching the query", "example": 10 }, "limit": { "type": "number", "description": "Number of items returned", "example": 20 }, "offset": { "type": "number", "description": "Number of items skipped", "example": 0 }, "hasMore": { "type": "boolean", "description": "Whether there are more items", "example": false }, "nextCursor": { "type": "string", "description": "Cursor for fetching next page", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "items", "total", "limit", "offset", "hasMore" ] }, "UpdateGitRegistryDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the registry within the organization", "example": "my-workloads-repo", "minLength": 2, "maxLength": 100 }, "url": { "type": "string", "description": "Git repository URL", "example": "https://github.com/org/workloads.git" }, "branch": { "type": "string", "description": "Branch to use", "example": "main" }, "path": { "type": "string", "description": "Path within the repository to scan for workloads", "example": "/workloads" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "HTTPS_TOKEN", "SSH_KEY" ], "example": "TOKEN" }, "credential": { "type": "string", "description": "Credential (token or SSH key) for authentication. Set to null to remove.", "example": "ghp_xxxxxxxxxxxxxxxxxxxx", "nullable": true }, "syncIntervalMinutes": { "type": "number", "description": "Sync interval in minutes", "example": 60, "minimum": 1, "maximum": 1440 }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "example": true } } }, "RejectedManifestDto": { "type": "object", "properties": { "path": { "type": "string", "description": "Path of the rejected manifest within the registry", "example": "applications/example-app/manifest.yaml" }, "reason": { "type": "string", "description": "Why the manifest was rejected at ingest", "example": "REJECTED deploymentProfiles[0].type: type \"quadlet\" is not permitted by Margo v1.0.0-rc2" } }, "required": [ "path", "reason" ] }, "GitRegistrySyncResultDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the sync operation completed successfully", "example": true }, "registryId": { "type": "string", "description": "The ID of the registry that was synced", "example": "550e8400-e29b-41d4-a716-446655440000" }, "scope": { "type": "string", "description": "The scope of the sync (always \"tenant\" for tenant registries)", "example": "tenant", "enum": [ "tenant" ] }, "applicationsFound": { "type": "number", "description": "Number of applications found in the repository", "example": 5 }, "applicationsImported": { "type": "number", "description": "Number of new applications imported", "example": 2 }, "applicationsUpdated": { "type": "number", "description": "Number of existing applications updated", "example": 3 }, "errors": { "description": "Array of error messages encountered during sync", "example": [], "type": "array", "items": { "type": "string" } }, "rejectedManifests": { "description": "Manifests rejected at ingest because every declared deployment profile failed rc2 admission (or none was declared). Distinct from errors — rejection is correct, intended behavior, not a sync failure — but must still be visible to the operator rather than showing up only as the application silently disappearing.", "type": "array", "items": { "$ref": "#/components/schemas/RejectedManifestDto" } }, "syncDuration": { "type": "number", "description": "Duration of the sync operation in milliseconds", "example": 1234 }, "commit": { "type": "string", "description": "The Git commit SHA that was synced", "example": "abc123def456" } }, "required": [ "success", "registryId", "scope", "applicationsFound", "applicationsImported", "applicationsUpdated", "errors", "rejectedManifests", "syncDuration" ] }, "CreateOciRegistryDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the registry within the organization", "example": "my-container-registry", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "description": "Description of the registry", "example": "Production container images", "maxLength": 500 }, "url": { "type": "string", "description": "OCI registry URL", "example": "https://registry.example.com" }, "registryType": { "type": "string", "description": "Registry type", "enum": [ "GENERIC" ], "default": "GENERIC", "example": "GENERIC" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "BASIC", "TOKEN" ], "default": "NONE", "example": "NONE" }, "credential": { "type": "string", "description": "Credential for authentication. Will be encrypted at rest. For BASIC auth this MUST be \"username:password\". For TOKEN auth it is the raw token.", "example": "username:password" }, "verifyTls": { "type": "boolean", "description": "Whether to verify TLS certificates", "default": true, "example": true }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "default": true, "example": true }, "repositories": { "description": "Repositories to sync, e.g. `library/nginx`. Registry-side catalog enumeration is not used (FM-839): an empty list syncs nothing.", "example": [ "library/nginx", "team/app" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name", "url" ] }, "OciRegistryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "Organization ID that owns this registry", "example": "550e8400-e29b-41d4-a716-446655440001" }, "name": { "type": "string", "description": "Registry name", "example": "my-container-registry" }, "description": { "type": "string", "description": "Registry description", "example": "Production container images", "nullable": true }, "url": { "type": "string", "description": "OCI registry URL", "example": "https://registry.example.com" }, "registryType": { "type": "string", "description": "Registry type", "enum": [ "GENERIC" ], "example": "GENERIC" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "BASIC", "TOKEN" ], "example": "NONE" }, "hasCredentials": { "type": "boolean", "description": "Whether credentials are configured", "example": false }, "verifyTls": { "type": "boolean", "description": "Whether TLS verification is enabled", "example": true }, "lastHealthCheck": { "format": "date-time", "type": "string", "description": "Last health check timestamp", "example": "2024-01-15T10:30:00Z", "nullable": true }, "healthStatus": { "type": "string", "description": "Health status (healthy, unhealthy, unknown)", "example": "healthy", "nullable": true }, "lastSyncAt": { "format": "date-time", "type": "string", "description": "Last sync timestamp", "example": "2024-01-15T10:30:00Z", "nullable": true }, "lastSyncError": { "type": "string", "description": "Last sync error message", "nullable": true }, "syncIntervalMinutes": { "type": "number", "description": "Sync interval in minutes", "example": 60 }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "example": true }, "repositories": { "description": "Repositories this registry syncs, e.g. `library/nginx`. Registry-side catalog enumeration is not used (FM-839): an empty list syncs nothing.", "example": [], "type": "array", "items": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organizationId", "name", "url", "registryType", "authType", "hasCredentials", "verifyTls", "syncIntervalMinutes", "enabled", "repositories", "createdAt", "updatedAt" ] }, "OciRegistryListResponseDto": { "type": "object", "properties": { "items": { "description": "List of OCI registries", "type": "array", "items": { "$ref": "#/components/schemas/OciRegistryResponseDto" } }, "total": { "type": "number", "description": "Total number of registries matching the query", "example": 10 }, "limit": { "type": "number", "description": "Number of items returned", "example": 20 }, "offset": { "type": "number", "description": "Number of items skipped", "example": 0 }, "hasMore": { "type": "boolean", "description": "Whether there are more items", "example": false }, "nextCursor": { "type": "string", "description": "Cursor for fetching next page", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "items", "total", "limit", "offset", "hasMore" ] }, "UpdateOciRegistryDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the registry within the organization", "example": "my-container-registry", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "description": "Description of the registry", "example": "Production container images", "maxLength": 500, "nullable": true }, "url": { "type": "string", "description": "OCI registry URL", "example": "https://registry.example.com" }, "registryType": { "type": "string", "description": "Registry type", "enum": [ "GENERIC" ], "example": "GENERIC" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "NONE", "BASIC", "TOKEN" ], "example": "BASIC" }, "credential": { "type": "string", "description": "Credential for authentication. Set to null to remove. For BASIC auth this MUST be \"username:password\". For TOKEN auth it is the raw token.", "example": "username:password", "nullable": true }, "verifyTls": { "type": "boolean", "description": "Whether to verify TLS certificates", "example": true }, "enabled": { "type": "boolean", "description": "Whether the registry is enabled", "example": true }, "repositories": { "description": "Repositories to sync, e.g. `library/nginx`. Replaces the stored list. Registry-side catalog enumeration is not used (FM-839): an empty list syncs nothing.", "example": [ "library/nginx", "team/app" ], "type": "array", "items": { "type": "string" } } } }, "OciRegistryHealthCheckResultDto": { "type": "object", "properties": { "healthy": { "type": "boolean", "description": "Whether the registry is healthy", "example": true }, "status": { "type": "string", "description": "Health status of the registry", "example": "healthy", "enum": [ "healthy", "unhealthy", "unknown" ] }, "error": { "type": "string", "description": "Error message if the health check failed", "example": "Connection timed out (10s)" }, "responseTimeMs": { "type": "number", "description": "Response time in milliseconds", "example": 150 } }, "required": [ "healthy", "status" ] }, "OciRegistrySyncResultDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the sync operation completed successfully", "example": true }, "registryId": { "type": "string", "description": "The ID of the registry that was synced", "example": "550e8400-e29b-41d4-a716-446655440000" }, "repositoriesFound": { "type": "number", "description": "Number of OCI repositories found in the registry", "example": 10 }, "applicationsFound": { "type": "number", "description": "Number of applications found in the registry", "example": 5 }, "applicationsImported": { "type": "number", "description": "Number of new applications imported", "example": 2 }, "applicationsUpdated": { "type": "number", "description": "Number of existing applications updated", "example": 3 }, "errors": { "description": "Array of error messages encountered during sync", "example": [], "type": "array", "items": { "type": "string" } }, "syncDuration": { "type": "number", "description": "Duration of the sync operation in milliseconds", "example": 1234 } }, "required": [ "success", "registryId", "repositoriesFound", "applicationsFound", "applicationsImported", "applicationsUpdated", "errors", "syncDuration" ] }, "OciRegistryPerRepositorySyncHistoryDto": { "type": "object", "properties": { "repository": { "type": "string", "example": "library/nginx" }, "tagCount": { "type": "number", "example": 12 }, "found": { "type": "number", "example": 3 }, "imported": { "type": "number", "example": 1 }, "updated": { "type": "number", "example": 2 }, "errors": { "example": [], "type": "array", "items": { "type": "string" } } }, "required": [ "repository", "tagCount", "found", "imported", "updated", "errors" ] }, "OciRegistrySyncHistoryEntryDto": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "registryId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "scope": { "type": "string", "enum": [ "tenant", "global" ] }, "organizationId": { "type": "object", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "status": { "type": "string", "enum": [ "success", "partial", "failed" ] }, "repositoriesFound": { "type": "number", "example": 10 }, "applicationsFound": { "type": "number", "example": 5 }, "applicationsImported": { "type": "number", "example": 2 }, "applicationsUpdated": { "type": "number", "example": 3 }, "errors": { "example": [], "type": "array", "items": { "type": "string" } }, "syncDurationMs": { "type": "number", "example": 1234 }, "perRepository": { "description": "Per-repository sync breakdown (FM-672)", "type": "array", "items": { "$ref": "#/components/schemas/OciRegistryPerRepositorySyncHistoryDto" } }, "triggeredBy": { "type": "object", "description": "User id (uuid) for manual runs, \"scheduler\" for cron, null when unknown", "example": "scheduler", "nullable": true }, "createdAt": { "type": "string", "example": "2026-06-08T12:34:56.000Z" } }, "required": [ "id", "registryId", "scope", "organizationId", "status", "repositoriesFound", "applicationsFound", "applicationsImported", "applicationsUpdated", "errors", "syncDurationMs", "perRepository", "triggeredBy", "createdAt" ] }, "OciRegistrySyncHistoryListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OciRegistrySyncHistoryEntryDto" } }, "total": { "type": "number", "example": 42 }, "hasMore": { "type": "boolean", "example": false }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "total", "hasMore" ] }, "FlecsStoreResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Store configuration ID", "format": "uuid" }, "organizationId": { "type": "string", "description": "Owning organization ID", "format": "uuid" }, "storeId": { "type": "number", "description": "FLECS store ID", "example": 89 }, "enabled": { "type": "boolean", "description": "Whether the store is active", "example": true }, "lastSyncAt": { "type": "string", "nullable": true, "description": "When the catalog was last synced (discovery phase)", "format": "date-time" }, "lastSyncError": { "type": "string", "nullable": true, "description": "Failure from the most recent discovery call (the store-id lookup itself). Does not reflect the outcome of the downstream OCI sync, which is tracked on the linked registry." }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "organizationId", "storeId", "enabled", "createdAt", "updatedAt" ] }, "UpsertFlecsStoreDto": { "type": "object", "properties": { "storeId": { "type": "number", "description": "FLECS store ID. Acts as a catalog-visibility filter and, per FLECS, a mandatory anti-cross-tenant-pollution control. logiccloud is store 89. Note that a wrong store ID returns a plausible full catalog rather than an error.", "example": 89, "minimum": 1 }, "enabled": { "type": "boolean", "description": "Whether the store is active.", "default": false, "example": false } }, "required": [ "storeId" ] }, "FlecsStorePerRepositorySyncHistoryDto": { "type": "object", "properties": { "repository": { "type": "string", "example": "catalog/com-example-gateway-app" }, "tagCount": { "type": "number", "example": 12 }, "found": { "type": "number", "example": 3 }, "imported": { "type": "number", "example": 1 }, "updated": { "type": "number", "example": 2 }, "errors": { "example": [], "type": "array", "items": { "type": "string" } } }, "required": [ "repository", "tagCount", "found", "imported", "updated", "errors" ] }, "FlecsStoreSyncResultDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "success", "empty", "partial", "failed" ] }, "registryId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "repositoriesFound": { "type": "number", "example": 10 }, "applicationsFound": { "type": "number", "example": 6 }, "applicationsImported": { "type": "number", "example": 4 }, "applicationsUpdated": { "type": "number", "example": 2 }, "versionsRemoved": { "type": "number", "example": 0 }, "versionsMarkedUnavailable": { "type": "number", "example": 0 }, "applicationsRemoved": { "type": "number", "example": 0 }, "errors": { "example": [], "type": "array", "items": { "type": "string" } }, "perRepository": { "type": "array", "items": { "$ref": "#/components/schemas/FlecsStorePerRepositorySyncHistoryDto" } }, "syncDuration": { "type": "number", "example": 1234 } }, "required": [ "success", "status", "registryId", "repositoriesFound", "applicationsFound", "applicationsImported", "applicationsUpdated", "versionsRemoved", "versionsMarkedUnavailable", "applicationsRemoved", "errors", "perRepository", "syncDuration" ] }, "FlecsStoreRepositoryProgressDto": { "type": "object", "properties": { "repository": { "type": "string", "example": "catalog/com-example-gateway-app" }, "status": { "type": "string", "enum": [ "pending", "checking", "added", "updated", "rejected" ] }, "reason": { "type": "string", "description": "Present when status is \"rejected\" — why nothing was imported/updated.", "example": "no Margo application manifest found in this repository" } }, "required": [ "repository", "status" ] }, "FlecsStoreSyncProgressDto": { "type": "object", "properties": { "registryId": { "type": "string", "nullable": true, "example": "550e8400-e29b-41d4-a716-446655440000", "description": "null when no sync is currently running for this store" }, "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/FlecsStoreRepositoryProgressDto" } }, "startedAt": { "type": "string", "nullable": true, "example": "2026-06-08T12:34:56.000Z" }, "updatedAt": { "type": "string", "nullable": true, "example": "2026-06-08T12:34:58.000Z" } }, "required": [ "registryId", "repositories", "startedAt", "updatedAt" ] }, "FlecsStoreSyncHistoryEntryDto": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "storeId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "scope": { "type": "string", "enum": [ "flecs" ] }, "organizationId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "status": { "type": "string", "enum": [ "success", "empty", "partial", "failed" ] }, "repositoriesFound": { "type": "number", "example": 10 }, "applicationsFound": { "type": "number", "example": 6 }, "applicationsImported": { "type": "number", "example": 4 }, "applicationsUpdated": { "type": "number", "example": 2 }, "errors": { "example": [], "type": "array", "items": { "type": "string" } }, "syncDurationMs": { "type": "number", "example": 1234 }, "perRepository": { "description": "Per-repository imported/updated breakdown for this run", "type": "array", "items": { "$ref": "#/components/schemas/FlecsStorePerRepositorySyncHistoryDto" } }, "triggeredBy": { "type": "string", "description": "User id (uuid) for manual runs, \"scheduler\" for cron, null when unknown", "example": "scheduler", "nullable": true }, "createdAt": { "type": "string", "example": "2026-06-08T12:34:56.000Z" } }, "required": [ "id", "storeId", "scope", "organizationId", "status", "repositoriesFound", "applicationsFound", "applicationsImported", "applicationsUpdated", "errors", "syncDurationMs", "perRepository", "triggeredBy", "createdAt" ] }, "FlecsStoreSyncHistoryListDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FlecsStoreSyncHistoryEntryDto" } }, "total": { "type": "number", "example": 12 }, "hasMore": { "type": "boolean", "example": false }, "nextCursor": { "type": "string" } }, "required": [ "data", "total", "hasMore" ] }, "SourceLinkDto": { "type": "object", "properties": { "registryType": { "type": "string", "description": "Registry type", "enum": [ "git", "oci" ] }, "registryId": { "type": "string", "description": "Registry ID" }, "registryName": { "type": "string", "description": "Registry name" }, "registryUrl": { "type": "string", "description": "Registry URL" }, "lastSeenAt": { "type": "string", "description": "When the version was last seen in this registry" } }, "required": [ "registryType", "registryId", "registryName", "lastSeenAt" ] }, "ApplicationDescriptionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the application description", "example": "550e8400-e29b-41d4-a716-446655440001" }, "applicationPackageId": { "type": "string", "description": "ID of the parent application package", "example": "550e8400-e29b-41d4-a716-446655440000" }, "applicationPackageName": { "type": "string", "description": "Name of the parent application package", "example": "Eclipse Mosquitto" }, "version": { "type": "string", "description": "Version string (semver)", "example": "2.0.18" }, "deploymentProfile": { "type": "string", "description": "Deployment profile type", "enum": [ "DOCKER_COMPOSE", "HELM", "K8S_MANIFEST", "PODMAN", "QUADLET" ], "example": "HELM" }, "manifest": { "type": "object", "description": "Full deployment manifest" }, "checksumSha256": { "type": "string", "description": "SHA-256 checksum of the package", "example": "a1b2c3d4e5f6..." }, "minMargoVersion": { "type": "string", "description": "Minimum Margo version required", "example": "1.0.0" }, "compatibleDevices": { "description": "List of compatible device types/constraints", "type": "array", "items": { "type": "object" } }, "resourceRequirements": { "type": "object", "description": "Resource requirements (CPU, memory, etc.)" }, "validationErrors": { "description": "List of validation errors if any", "type": "array", "items": { "type": "object" } }, "usesDeprecatedSchema": { "type": "boolean", "description": "True when the stored manifest still carries the retired packageLocation/keyLocation component-artifact fields instead of repository+revision (ADR-0010-1 / FM-1090). Such a description will not deploy until republished/resynced under the new schema.", "example": false }, "availability": { "type": "string", "description": "Application availability status", "enum": [ "AVAILABLE", "SOURCE_UNAVAILABLE" ], "example": "AVAILABLE" }, "sourceLinks": { "description": "Source repository links for this version", "type": "array", "items": { "$ref": "#/components/schemas/SourceLinkDto" } }, "createdAt": { "type": "string", "description": "When this version was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "description": "When this version was last updated", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "applicationPackageId", "applicationPackageName", "version", "deploymentProfile", "manifest", "compatibleDevices", "resourceRequirements", "validationErrors", "usesDeprecatedSchema", "createdAt", "updatedAt" ] }, "ApplicationWithLatestVersionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the application package", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "Organization that owns this application", "example": "550e8400-e29b-41d4-a716-446655440002" }, "name": { "type": "string", "description": "Application name", "example": "Eclipse Mosquitto" }, "description": { "type": "string", "description": "Application description", "example": "Lightweight MQTT broker for IoT" }, "descriptionMarkdown": { "type": "string", "description": "Detailed markdown description of the application", "example": "# Mosquitto\n\nLightweight MQTT broker for IoT deployments." }, "releaseNotes": { "type": "string", "description": "Release notes for the current version", "example": "## Version 2.0.18\n\n- Security fixes\n- Performance improvements" }, "descriptionFile": { "type": "string", "description": "URL or path to detailed description file (Markdown)", "example": "/api/v1/applications/550e8400.../files/description" }, "releaseNotesFile": { "type": "string", "description": "URL or path to release notes file (Markdown or PDF)", "example": "/api/v1/applications/550e8400.../files/release-notes" }, "licenseFile": { "type": "string", "description": "URL or path to license file (text, Markdown, or PDF)", "example": "/api/v1/applications/550e8400.../files/license" }, "licenseText": { "type": "string", "description": "Inline license text content", "example": "MIT License\n\nCopyright (c) 2024..." }, "vendor": { "type": "string", "description": "Vendor/author name", "example": "Eclipse Foundation" }, "category": { "type": "string", "description": "Category classification", "example": "IoT" }, "iconUrl": { "type": "string", "description": "URL to application icon", "example": "/api/v1/applications/550e8400.../icon" }, "availability": { "type": "string", "description": "Application availability status", "enum": [ "AVAILABLE", "SOURCE_UNAVAILABLE" ], "example": "AVAILABLE" }, "metadata": { "type": "object", "description": "Additional metadata" }, "versionCount": { "type": "number", "description": "Number of versions available", "example": 3 }, "latestVersion": { "type": "string", "description": "Latest version string", "example": "2.0.18" }, "createdAt": { "type": "string", "description": "When the package was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "description": "When the package was last updated", "example": "2024-01-15T10:30:00Z" }, "latestDescription": { "description": "Details of the latest version", "allOf": [ { "$ref": "#/components/schemas/ApplicationDescriptionDto" } ] } }, "required": [ "id", "organizationId", "name", "metadata", "versionCount", "createdAt", "updatedAt" ] }, "ApplicationListResponseDto": { "type": "object", "properties": { "data": { "description": "List of applications", "type": "array", "items": { "$ref": "#/components/schemas/ApplicationWithLatestVersionDto" } }, "total": { "type": "number", "description": "Total number of applications matching the query", "example": 42 }, "hasMore": { "type": "boolean", "description": "Whether there are more results available", "example": true }, "nextCursor": { "type": "string", "description": "Cursor for fetching the next page", "example": "eyJpZCI6IjEyMzQ1In0=" } }, "required": [ "data", "total", "hasMore" ] }, "CategoriesResponseDto": { "type": "object", "properties": { "data": { "description": "List of unique categories", "example": [ "IoT", "Database", "Monitoring" ], "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "VendorsResponseDto": { "type": "object", "properties": { "data": { "description": "List of unique vendors", "example": [ "Eclipse Foundation", "Apache", "HashiCorp" ], "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "ApplicationPackageDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the application package", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "Organization that owns this application", "example": "550e8400-e29b-41d4-a716-446655440002" }, "name": { "type": "string", "description": "Application name", "example": "Eclipse Mosquitto" }, "description": { "type": "string", "description": "Application description", "example": "Lightweight MQTT broker for IoT" }, "descriptionMarkdown": { "type": "string", "description": "Detailed markdown description of the application", "example": "# Mosquitto\n\nLightweight MQTT broker for IoT deployments." }, "releaseNotes": { "type": "string", "description": "Release notes for the current version", "example": "## Version 2.0.18\n\n- Security fixes\n- Performance improvements" }, "descriptionFile": { "type": "string", "description": "URL or path to detailed description file (Markdown)", "example": "/api/v1/applications/550e8400.../files/description" }, "releaseNotesFile": { "type": "string", "description": "URL or path to release notes file (Markdown or PDF)", "example": "/api/v1/applications/550e8400.../files/release-notes" }, "licenseFile": { "type": "string", "description": "URL or path to license file (text, Markdown, or PDF)", "example": "/api/v1/applications/550e8400.../files/license" }, "licenseText": { "type": "string", "description": "Inline license text content", "example": "MIT License\n\nCopyright (c) 2024..." }, "vendor": { "type": "string", "description": "Vendor/author name", "example": "Eclipse Foundation" }, "category": { "type": "string", "description": "Category classification", "example": "IoT" }, "iconUrl": { "type": "string", "description": "URL to application icon", "example": "/api/v1/applications/550e8400.../icon" }, "availability": { "type": "string", "description": "Application availability status", "enum": [ "AVAILABLE", "SOURCE_UNAVAILABLE" ], "example": "AVAILABLE" }, "metadata": { "type": "object", "description": "Additional metadata" }, "versionCount": { "type": "number", "description": "Number of versions available", "example": 3 }, "latestVersion": { "type": "string", "description": "Latest version string", "example": "2.0.18" }, "createdAt": { "type": "string", "description": "When the package was created", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "description": "When the package was last updated", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organizationId", "name", "metadata", "versionCount", "createdAt", "updatedAt" ] }, "ApplicationDetailsResponseDto": { "type": "object", "properties": { "data": { "description": "Application package details with all versions", "allOf": [ { "$ref": "#/components/schemas/ApplicationPackageDto" } ] } }, "required": [ "data" ] }, "ApplicationVersionsResponseDto": { "type": "object", "properties": { "data": { "description": "List of application versions", "type": "array", "items": { "$ref": "#/components/schemas/ApplicationDescriptionDto" } }, "total": { "type": "number", "description": "Total number of versions", "example": 5 } }, "required": [ "data", "total" ] }, "TriggerRollbackDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Operator-supplied reason for the rollback, recorded in the audit trail", "maxLength": 500, "example": "Canary devices reported repeated container crashes" } } }, "DeviceSelectorExpressionDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Label key to match on", "example": "line" }, "operator": { "type": "string", "enum": [ "In", "NotIn", "Exists", "DoesNotExist" ], "example": "In" }, "values": { "example": [ "line-3" ], "type": "array", "items": { "type": "string" } } }, "required": [ "key", "operator" ] }, "DeviceSelectorDto": { "type": "object", "properties": { "matchLabels": { "type": "object", "description": "Exact label equality match; all entries must match (AND).", "example": { "site": "plant-a" } }, "matchExpressions": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceSelectorExpressionDto" } } } }, "RollbackDevicesBySelectorDto": { "type": "object", "properties": { "deviceSelector": { "description": "Label selector choosing which devices to roll back", "allOf": [ { "$ref": "#/components/schemas/DeviceSelectorDto" } ] }, "reason": { "type": "string", "description": "Operator-supplied reason, recorded on the audit entry", "maxLength": 500 }, "applicationPackageId": { "type": "string", "description": "Which application package to roll back on every matching device.", "format": "uuid" } }, "required": [ "deviceSelector" ] }, "RollbackDeviceVersionDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Operator-supplied reason, recorded on the audit entry", "maxLength": 500, "example": "v2.4.1 crash-looping on the line-3 gateways" }, "applicationPackageId": { "type": "string", "description": "Which application to roll back. Rollback is scoped to one application package; on a device running several, omitting this picks the most recently sealed rollbackable one.", "format": "uuid" } } }, "MetricSnapshotDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Snapshot ID" }, "deviceId": { "type": "string", "description": "Device ID" }, "timestamp": { "type": "string", "description": "Timestamp of the snapshot" }, "cpuUsagePercent": { "type": "object", "description": "CPU usage percentage (0-100)" }, "memoryUsedBytes": { "type": "object", "description": "Memory used in bytes" }, "memoryTotalBytes": { "type": "object", "description": "Memory total in bytes" }, "memoryUsagePercent": { "type": "object", "description": "Memory usage percentage (computed)" }, "diskUsedBytes": { "type": "object", "description": "Disk used in bytes" }, "diskTotalBytes": { "type": "object", "description": "Disk total in bytes" }, "diskUsagePercent": { "type": "object", "description": "Disk usage percentage (computed)" }, "uptimeSeconds": { "type": "object", "description": "System uptime in seconds" }, "restartCount": { "type": "object", "description": "Number of restarts" }, "containersRunning": { "type": "object", "description": "Running containers count" }, "containersFailed": { "type": "object", "description": "Failed containers count" }, "errorCount": { "type": "number", "description": "Error count in the aggregation window" } }, "required": [ "id", "deviceId", "timestamp" ] }, "TelemetryListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSnapshotDto" } }, "total": { "type": "number", "description": "Total number of snapshots in range" } }, "required": [ "data", "total" ] }, "RawMetricDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Full VictoriaMetrics metric name, e.g. fm_device_disk_used_bytes" }, "value": { "type": "number", "description": "Latest sample value" }, "timestamp": { "type": "string", "description": "Timestamp of the latest sample (ISO 8601)" } }, "required": [ "name", "value", "timestamp" ] }, "RawMetricsResponseDto": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/RawMetricDto" } } }, "required": [ "metrics" ] }, "LogEntryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Log entry ID" }, "deviceId": { "type": "string", "description": "Device ID" }, "timestamp": { "type": "string", "description": "Timestamp" }, "severity": { "type": "string", "description": "Severity level", "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ] }, "body": { "type": "string", "description": "Log message body" }, "source": { "type": "object", "description": "Log source (container name, service, or system)" }, "attributes": { "type": "object", "description": "Structured attributes" } }, "required": [ "id", "deviceId", "timestamp", "severity", "body" ] }, "LogListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntryDto" } }, "hasMore": { "type": "boolean", "description": "Whether there are more entries before the cursor" } }, "required": [ "data", "hasMore" ] }, "LogSourcesResponseDto": { "type": "object", "properties": { "sources": { "description": "Distinct workload/container/service `source` values seen for this device within the log retention window, sorted alphabetically. Populates the workload picker without the caller having to scan the full log.", "example": [ "edge-agent", "my-container", "system" ], "type": "array", "items": { "type": "string" } } }, "required": [ "sources" ] }, "DeviceHealthSummaryDto": { "type": "object", "properties": { "deviceId": { "type": "string" }, "deviceName": { "type": "string" }, "cpuUsagePercent": { "type": "object" }, "memoryUsagePercent": { "type": "object" }, "diskUsagePercent": { "type": "object" } }, "required": [ "deviceId", "deviceName" ] }, "RecentErrorDto": { "type": "object", "properties": { "deviceId": { "type": "string" }, "deviceName": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "deviceId", "deviceName", "message", "timestamp" ] }, "FleetHealthResponseDto": { "type": "object", "properties": { "totalDevices": { "type": "number", "description": "Total devices in organization" }, "onlineDevices": { "type": "number", "description": "Devices currently online" }, "offlineDevices": { "type": "number", "description": "Devices currently offline" }, "errorDevices": { "type": "number", "description": "Devices in error state" }, "avgCpuPercent": { "type": "object", "description": "Average CPU usage across fleet (%)" }, "avgMemPercent": { "type": "object", "description": "Average memory usage across fleet (%)" }, "avgDiskPercent": { "type": "object", "description": "Average disk usage across fleet (%)" }, "devicesWithHighCpu": { "description": "Devices with CPU usage above 90%", "type": "array", "items": { "$ref": "#/components/schemas/DeviceHealthSummaryDto" } }, "devicesLowDisk": { "description": "Devices with disk usage above 85%", "type": "array", "items": { "$ref": "#/components/schemas/DeviceHealthSummaryDto" } }, "recentErrors": { "description": "Recent error log entries across fleet", "type": "array", "items": { "$ref": "#/components/schemas/RecentErrorDto" } } }, "required": [ "totalDevices", "onlineDevices", "offlineDevices", "errorDevices", "devicesWithHighCpu", "devicesLowDisk", "recentErrors" ] }, "WsTicketResponseDto": { "type": "object", "properties": { "ticket": { "type": "string", "description": "Opaque single-use handshake ticket. Pass it as the `ticket` query parameter on the WebSocket upgrade. It carries no claims and is consumed on first redemption.", "example": "a3f1c0de9b2447e8a1d6f05c7b3e9821a3f1c0de9b2447e8a1d6f05c7b3e9821" }, "expiresIn": { "type": "number", "description": "Ticket lifetime in seconds. Redeem it immediately; it is not a session token.", "example": 60 } }, "required": [ "ticket", "expiresIn" ] }, "AlertRuleTargetSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Ops on-call email" }, "channel": { "type": "string", "example": "EMAIL" }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "channel", "enabled" ] }, "AlertRuleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "CPU above 80% on edge nodes" }, "ruleType": { "type": "string", "enum": [ "DEVICE_OFFLINE", "METRIC_THRESHOLD", "WORKLOAD_CRASH" ] }, "scope": { "type": "string", "enum": [ "GLOBAL", "LABEL", "DEVICE" ] }, "targetId": { "type": "object", "format": "uuid", "nullable": true }, "targetLabels": { "type": "object", "additionalProperties": { "type": "string" } }, "expression": { "type": "object", "example": "cpu > 80 for 5m", "nullable": true }, "thresholdMinutes": { "type": "object", "nullable": true }, "enabled": { "type": "boolean" }, "notificationTargets": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleTargetSummaryDto" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "ruleType", "scope", "targetLabels", "enabled", "notificationTargets", "createdAt", "updatedAt" ] }, "AlertDeliveryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ruleId": { "type": "string", "format": "uuid" }, "ruleName": { "type": "string", "example": "CPU above 80% on edge nodes" }, "deviceId": { "type": "object", "format": "uuid", "nullable": true }, "notificationTargetId": { "type": "string", "format": "uuid" }, "notificationTargetName": { "type": "string", "example": "Ops on-call email" }, "channel": { "type": "string", "example": "EMAIL" }, "state": { "type": "string", "enum": [ "OPEN", "RESOLVED" ] }, "firedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": "object", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "object", "format": "date-time", "nullable": true, "description": "When the transport confirmed delivery. Null while pending or failed." }, "error": { "type": "object", "nullable": true, "description": "Transport failure detail after the retry budget was exhausted." } }, "required": [ "id", "ruleId", "ruleName", "notificationTargetId", "notificationTargetName", "channel", "state", "firedAt" ] }, "AlertDeliveryListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDeliveryResponseDto" } }, "total": { "type": "number", "description": "Total matching records, ignoring limit/offset", "example": 128 } }, "required": [ "items", "total" ] }, "CreateAlertRuleDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable rule name", "example": "CPU above 80% on edge nodes" }, "ruleType": { "type": "string", "description": "Condition family the rule evaluates", "enum": [ "DEVICE_OFFLINE", "METRIC_THRESHOLD", "WORKLOAD_CRASH" ], "example": "METRIC_THRESHOLD" }, "scope": { "type": "string", "description": "Which devices the rule applies to. GLOBAL covers every device in the organization; LABEL matches the selector in targetLabels; DEVICE matches the single device in targetId.", "enum": [ "GLOBAL", "LABEL", "DEVICE" ], "default": "GLOBAL" }, "targetId": { "type": "string", "description": "Device id. Required when scope is DEVICE, ignored otherwise.", "format": "uuid" }, "targetLabels": { "type": "object", "description": "Label selector. Required when scope is LABEL, ignored otherwise. A device matches when every key/value pair is present on its labels.", "additionalProperties": { "type": "string" }, "example": { "site": "berlin", "tier": "edge" } }, "expression": { "type": "string", "description": "Condition expression. Required for METRIC_THRESHOLD and WORKLOAD_CRASH; ignored for DEVICE_OFFLINE, which uses thresholdMinutes. Syntax: `field op value [AND field op value ...] [for ]`, where duration is e.g. 30s, 5m, 2h. Fields: cpu, memory, disk (percentages), restarts, containersFailed, containersRunning, errors, uptime, device.status, device.name, device.label..", "example": "cpu > 80 AND device.label.tier = \"edge\" for 5m" }, "thresholdMinutes": { "type": "number", "description": "DEVICE_OFFLINE only: minutes without a heartbeat before the rule fires. Defaults to 5 per FR-FM-021.", "minimum": 1, "maximum": 1440, "default": 5 }, "enabled": { "type": "boolean", "description": "Whether the rule is evaluated", "default": true }, "notificationTargetIds": { "description": "Notification targets to deliver this rule’s alerts to. Ids belonging to another organization are rejected.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name", "ruleType" ] }, "UpdateAlertRuleDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable rule name", "example": "CPU above 80% on edge nodes" }, "ruleType": { "type": "string", "description": "Condition family the rule evaluates", "enum": [ "DEVICE_OFFLINE", "METRIC_THRESHOLD", "WORKLOAD_CRASH" ], "example": "METRIC_THRESHOLD" }, "scope": { "type": "string", "description": "Which devices the rule applies to. GLOBAL covers every device in the organization; LABEL matches the selector in targetLabels; DEVICE matches the single device in targetId.", "enum": [ "GLOBAL", "LABEL", "DEVICE" ], "default": "GLOBAL" }, "targetId": { "type": "string", "description": "Device id. Required when scope is DEVICE, ignored otherwise.", "format": "uuid" }, "targetLabels": { "type": "object", "description": "Label selector. Required when scope is LABEL, ignored otherwise. A device matches when every key/value pair is present on its labels.", "additionalProperties": { "type": "string" }, "example": { "site": "berlin", "tier": "edge" } }, "expression": { "type": "string", "description": "Condition expression. Required for METRIC_THRESHOLD and WORKLOAD_CRASH; ignored for DEVICE_OFFLINE, which uses thresholdMinutes. Syntax: `field op value [AND field op value ...] [for ]`, where duration is e.g. 30s, 5m, 2h. Fields: cpu, memory, disk (percentages), restarts, containersFailed, containersRunning, errors, uptime, device.status, device.name, device.label..", "example": "cpu > 80 AND device.label.tier = \"edge\" for 5m" }, "thresholdMinutes": { "type": "number", "description": "DEVICE_OFFLINE only: minutes without a heartbeat before the rule fires. Defaults to 5 per FR-FM-021.", "minimum": 1, "maximum": 1440, "default": 5 }, "enabled": { "type": "boolean", "description": "Whether the rule is evaluated", "default": true }, "notificationTargetIds": { "description": "Notification targets to deliver this rule’s alerts to. Ids belonging to another organization are rejected.", "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "TestFireTargetResultDto": { "type": "object", "properties": { "notificationTargetId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Ops on-call email" }, "channel": { "type": "string", "example": "EMAIL" }, "delivered": { "type": "boolean", "description": "Whether the transport accepted the test notification" }, "error": { "type": "string", "description": "Failure detail when delivered is false; empty otherwise.", "example": "" } }, "required": [ "notificationTargetId", "name", "channel", "delivered", "error" ] }, "TestFireResponseDto": { "type": "object", "properties": { "ruleId": { "type": "string", "format": "uuid" }, "conditionCurrentlyMet": { "type": "boolean", "description": "What the rule evaluates to against current data right now. Independent of whether the test notification was delivered — a rule can be not-currently-matching and still have perfectly working targets." }, "matchedDeviceCount": { "type": "number", "description": "Number of devices the rule’s scope currently resolves to.", "example": 12 }, "condition": { "type": "string", "description": "Human-readable rendering of the condition, as the evaluator sees it.", "example": "cpu > 80 for 300s" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TestFireTargetResultDto" } } }, "required": [ "ruleId", "conditionCurrentlyMet", "matchedDeviceCount", "condition", "results" ] }, "NotificationTargetResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Ops on-call email" }, "channel": { "type": "string", "enum": [ "EMAIL", "WEBHOOK" ] }, "email": { "type": "object", "description": "EMAIL targets only", "nullable": true }, "url": { "type": "object", "description": "WEBHOOK targets only", "nullable": true }, "headers": { "type": "object", "description": "WEBHOOK targets only", "additionalProperties": { "type": "string" } }, "signed": { "type": "boolean", "description": "Whether webhook deliveries to this target are signed" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "channel", "signed", "enabled", "createdAt", "updatedAt" ] }, "CreateNotificationTargetDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable target name", "example": "Ops on-call email" }, "channel": { "type": "string", "description": "Delivery transport", "enum": [ "EMAIL", "WEBHOOK" ] }, "email": { "type": "string", "description": "Recipient address. Required when channel is EMAIL.", "example": "ops@example.com" }, "url": { "type": "string", "description": "Endpoint to POST to. Required when channel is WEBHOOK. Must be a public http(s) URL — private, loopback, link-local and in-cluster addresses are rejected to prevent SSRF.", "example": "https://hooks.example.com/services/T000/B000/XXXX" }, "headers": { "type": "object", "description": "Extra headers sent on every webhook delivery. WEBHOOK only.", "additionalProperties": { "type": "string" }, "example": { "X-Tenant-Token": "abc123" } }, "secret": { "type": "string", "description": "HMAC-SHA256 key used to sign webhook deliveries (X-Webhook-Signature). WEBHOOK only. Generated automatically when omitted — it is returned once on create and never again." }, "enabled": { "type": "boolean", "description": "Whether the target receives deliveries", "default": true } }, "required": [ "name", "channel" ] }, "CreatedNotificationTargetResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Ops on-call email" }, "channel": { "type": "string", "enum": [ "EMAIL", "WEBHOOK" ] }, "email": { "type": "object", "description": "EMAIL targets only", "nullable": true }, "url": { "type": "object", "description": "WEBHOOK targets only", "nullable": true }, "headers": { "type": "object", "description": "WEBHOOK targets only", "additionalProperties": { "type": "string" } }, "signed": { "type": "boolean", "description": "Whether webhook deliveries to this target are signed" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "object", "description": "HMAC-SHA256 signing key for webhook deliveries. Shown once, on creation, and never returned again. Store it in the receiving system to verify X-Webhook-Signature.", "nullable": true } }, "required": [ "id", "name", "channel", "signed", "enabled", "createdAt", "updatedAt" ] }, "UpdateNotificationTargetDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable target name", "example": "Ops on-call email" }, "channel": { "type": "string", "description": "Delivery transport", "enum": [ "EMAIL", "WEBHOOK" ] }, "email": { "type": "string", "description": "Recipient address. Required when channel is EMAIL.", "example": "ops@example.com" }, "url": { "type": "string", "description": "Endpoint to POST to. Required when channel is WEBHOOK. Must be a public http(s) URL — private, loopback, link-local and in-cluster addresses are rejected to prevent SSRF.", "example": "https://hooks.example.com/services/T000/B000/XXXX" }, "headers": { "type": "object", "description": "Extra headers sent on every webhook delivery. WEBHOOK only.", "additionalProperties": { "type": "string" }, "example": { "X-Tenant-Token": "abc123" } }, "secret": { "type": "string", "description": "HMAC-SHA256 key used to sign webhook deliveries (X-Webhook-Signature). WEBHOOK only. Generated automatically when omitted — it is returned once on create and never again." }, "enabled": { "type": "boolean", "description": "Whether the target receives deliveries", "default": true } } } } } }