{"openapi":"3.0.3","info":{"version":"1.0.0","contact":{"name":"API Support","email":"support@contexthub.dev"},"title":"Context Hub - Applications API","description":"Application management system with soft delete functionality and reference checking."},"servers":[{"url":"http://localhost:3000","description":"Development Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Application":{"type":"object","required":["name"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","readOnly":true},"name":{"type":"string","description":"Unique name for the application","example":"mobile-app"},"displayName":{"type":"string","description":"Human-readable name","example":"Mobile Application"},"description":{"type":"string","description":"Application description","example":"Primary mobile application for iOS and Android"},"clientId":{"type":"string","description":"Client ID for authentication","example":"mobile-client-123"},"metadata":{"type":"object","description":"Additional application-specific metadata","example":{"version":"1.0.0","platform":"ios,android"}},"isActive":{"type":"boolean","description":"Whether this application is active","default":true},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","readOnly":true},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","readOnly":true},"deletedAt":{"type":"string","format":"date-time","description":"Soft delete timestamp","nullable":true,"readOnly":true}}},"ApplicationList":{"type":"object","properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"ApplicationStats":{"type":"object","properties":{"userCount":{"type":"integer","description":"Number of users with profiles in this application"},"activeUserCount":{"type":"integer","description":"Number of active users"},"jwtAuditCount":{"type":"integer","description":"Total JWT verification attempts"},"recentJwtAudits":{"type":"integer","description":"JWT audits in last 24 hours"},"lastActivity":{"type":"string","format":"date-time","description":"Most recent JWT verification"},"phases":{"type":"object","description":"Count of users in each phase"}}},"ApplicationReferences":{"type":"object","properties":{"applicationId":{"type":"string"},"canDelete":{"type":"boolean","description":"Whether the application can be safely deleted"},"references":{"type":"object","properties":{"userProfiles":{"type":"object","properties":{"count":{"type":"integer"},"activeUsers":{"type":"integer"},"samples":{"type":"array","items":{"type":"object"}}}},"jwtAudits":{"type":"object","properties":{"count":{"type":"integer"},"recentCount":{"type":"integer"},"lastActivity":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable message about deletion possibility"}}},"UserAssignment":{"type":"object","required":["userId"],"properties":{"id":{"type":"string","format":"uuid","description":"Assignment unique identifier","readOnly":true},"userId":{"type":"string","format":"uuid","description":"ContextHub user UUID"},"applicationId":{"type":"string","format":"uuid","description":"Application UUID","readOnly":true},"appUserUuid":{"type":"string","format":"uuid","description":"Application-specific user UUID (auto-generated if not provided)"},"role":{"type":"string","enum":["user","admin","developer","manager","viewer"],"default":"user","description":"User's role in this application"},"permissions":{"type":"array","items":{"type":"string"},"default":[],"description":"Application-specific permissions","example":["read:content","write:profile","delete:own"]},"isActive":{"type":"boolean","default":true,"description":"Whether this assignment is active"},"metadata":{"type":"object","description":"Additional assignment-specific metadata","example":{"assignedBy":"admin@example.com","assignmentDate":"2024-01-15","department":"Engineering"}},"createdAt":{"type":"string","format":"date-time","description":"Assignment creation timestamp","readOnly":true},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","readOnly":true},"user":{"type":"object","description":"User details (when included)","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"fullName":{"type":"string"},"username":{"type":"string"},"isActive":{"type":"boolean"},"role":{"type":"string"}}}}},"AssignmentList":{"type":"object","properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/UserAssignment"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"responses":{"PermissionDenied":{"description":"Insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Insufficient permissions"},"message":{"type":"string","example":"This API key does not have the required permission"},"required":{"type":"string","example":"CREATE"},"available":{"type":"array","items":{"type":"string"},"example":["READ"]}}}}}}}},"paths":{"/api/v1/applications":{"get":{"summary":"List all applications","tags":["Applications - Core Management"],"security":[{"ApiKeyAuth":[]}],"description":"Get a list of all applications with optional filtering and pagination.\n**Required Permission: READ**\n","parameters":[{"in":"query","name":"name","schema":{"type":"string"},"description":"Filter by application name"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"includeDeleted","schema":{"type":"boolean","default":false},"description":"Include soft-deleted applications"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search in name, display name, or description"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["name","displayName","createdAt","updatedAt"],"default":"name"},"description":"Field to order by"},{"in":"query","name":"orderDirection","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Order direction"},{"in":"query","name":"includeStats","schema":{"type":"boolean","default":false},"description":"Include user count and activity statistics"}],"responses":{"200":{"description":"List of applications","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationList"}}}},"400":{"description":"Invalid query parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}},"post":{"summary":"Create a new application","tags":["Applications - Core Management"],"security":[{"ApiKeyAuth":[]}],"description":"Create a new application.\n**Required Permission: CREATE**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Unique name for the application"},"displayName":{"type":"string","description":"Human-readable name"},"description":{"type":"string","description":"Application description"},"clientId":{"type":"string","description":"Client ID for authentication"},"metadata":{"type":"object","description":"Additional metadata"},"isActive":{"type":"boolean","default":true,"description":"Whether the application is active"}}},"example":{"name":"web-portal","displayName":"Web Portal","description":"Main web application portal","clientId":"web-client-456","metadata":{"version":"2.0.0","environment":"production"}}}}},"responses":{"201":{"description":"Application created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"application":{"$ref":"#/components/schemas/Application"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"409":{"description":"Application with the same name already exists"}}}},"/api/v1/applications/{id}":{"get":{"summary":"Get application by ID","tags":["Applications - Core Management"],"security":[{"ApiKeyAuth":[]}],"description":"Get a single application by its ID.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"includeDeleted","schema":{"type":"boolean","default":false},"description":"Include application even if soft-deleted"},{"in":"query","name":"includeStats","schema":{"type":"boolean","default":true},"description":"Include detailed statistics"}],"responses":{"200":{"description":"Application details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Application"},{"type":"object","properties":{"stats":{"$ref":"#/components/schemas/ApplicationStats"}}}]}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}},"put":{"summary":"Update an application","tags":["Applications - Core Management"],"security":[{"ApiKeyAuth":[]}],"description":"Update an existing application.\n**Required Permission: UPDATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"clientId":{"type":"string"},"metadata":{"type":"object"},"isActive":{"type":"boolean"}}},"example":{"displayName":"Updated Web Portal","description":"Updated description","isActive":false}}}},"responses":{"200":{"description":"Application updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"application":{"$ref":"#/components/schemas/Application"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"},"409":{"description":"Application with the same name already exists"}}},"delete":{"summary":"Soft delete an application","tags":["Applications - Lifecycle"],"security":[{"ApiKeyAuth":[]}],"description":"Soft delete an application. This will fail if the application has associated user profiles or recent JWT audits.\n**Required Permission: DELETE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"force","schema":{"type":"boolean","default":false},"description":"Force delete even if references exist (admin only)"}],"responses":{"200":{"description":"Application deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deletedAt":{"type":"string","format":"date-time"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"},"409":{"description":"Cannot delete application with associated references","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"error":{"type":"string"}}},{"$ref":"#/components/schemas/ApplicationReferences"}]}}}}}}},"/api/v1/applications/{id}/force":{"delete":{"summary":"Force delete an application (admin only)","tags":["Applications - Lifecycle"],"security":[{"ApiKeyAuth":[]}],"description":"Force delete an application and all its associated data. This is a destructive operation.\n**Required Permission: DELETE (with full admin permissions)**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"confirm","schema":{"type":"boolean"},"description":"Must be set to true to confirm force deletion","required":true}],"responses":{"200":{"description":"Application and all references deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"deletedReferences":{"type":"object","properties":{"userProfiles":{"type":"integer"},"jwtAudits":{"type":"integer"}}}}}}}},"400":{"description":"Confirmation required"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}}},"/api/v1/applications/{id}/restore":{"post":{"summary":"Restore a soft-deleted application","tags":["Applications - Lifecycle"],"security":[{"ApiKeyAuth":[]}],"description":"Restore a previously soft-deleted application.\n**Required Permission: CREATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"responses":{"200":{"description":"Application restored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"application":{"$ref":"#/components/schemas/Application"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found or not deleted"},"409":{"description":"Cannot restore - name conflict with existing application"}}}},"/api/v1/applications/{id}/assign":{"post":{"summary":"Assign a user to an application","tags":["Applications - User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Assign a user to an application with specific role and permissions. This is an admin operation.\n**Required Permission: CREATE** (API Key) **OR** **admin role** (JWT)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","format":"uuid","description":"ContextHub user UUID"},"appUserUuid":{"type":"string","format":"uuid","description":"App-specific UUID (auto-generated if not provided)"},"role":{"type":"string","enum":["user","admin","developer","manager","viewer"],"default":"user","description":"User's role in this application"},"permissions":{"type":"array","items":{"type":"string"},"default":[],"description":"Application-specific permissions","example":["read:content","write:profile"]},"isActive":{"type":"boolean","default":true,"description":"Whether the assignment should be active"},"metadata":{"type":"object","description":"Additional assignment metadata","example":{"assignedBy":"admin@example.com","department":"Engineering"}}}},"example":{"userId":"123e4567-e89b-12d3-a456-426614174001","role":"developer","permissions":["read:content","write:code","debug:access"],"metadata":{"assignedBy":"admin@company.com","startDate":"2024-01-15"}}}}},"responses":{"201":{"description":"User assigned to application successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User assigned to application successfully"},"assignment":{"$ref":"#/components/schemas/UserAssignment"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application or User not found"},"409":{"description":"User already assigned to application or appUserUuid conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"User is already assigned to this application"}}}}}}}}},"/api/v1/applications/{id}/assigned-users":{"get":{"summary":"List users assigned to an application","tags":["Applications - User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Get a paginated list of users assigned to an application with filtering options.\n**Required Permission: READ** (API Key) **OR** **admin role** (JWT)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"role","schema":{"type":"string","enum":["user","admin","developer","manager","viewer"]},"description":"Filter by user role"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by assignment active status"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search in user email, name, or username"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["createdAt","updatedAt","role","isActive"],"default":"createdAt"},"description":"Field to order by"},{"in":"query","name":"orderDirection","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Order direction"},{"in":"query","name":"includeUser","schema":{"type":"boolean","default":true},"description":"Include user details in response"}],"responses":{"200":{"description":"List of user assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentList"}}}},"400":{"description":"Invalid query parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}}},"/api/v1/applications/{id}/users":{"get":{"summary":"Get users associated with this application","tags":["Applications - User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Get a list of users who have profiles in this application.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by user profile active status"},{"in":"query","name":"role","schema":{"type":"string"},"description":"Filter by user role in application"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"List of users with application profiles","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"appUserUuid":{"type":"string"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"email":{"type":"string"},"fullName":{"type":"string"},"username":{"type":"string"}}}}}},"pagination":{"type":"object"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}}},"/api/v1/applications/{id}/users/{userId}":{"put":{"summary":"Update user assignment to application","tags":["Applications - User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Update an existing user assignment to an application.\n**Required Permission: UPDATE** (API Key) **OR** **admin role** (JWT)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appUserUuid":{"type":"string","format":"uuid","description":"Update app-specific UUID"},"role":{"type":"string","enum":["user","admin","developer","manager","viewer"],"description":"Update user's role"},"permissions":{"type":"array","items":{"type":"string"},"description":"Update permissions array"},"isActive":{"type":"boolean","description":"Update active status"},"metadata":{"type":"object","description":"Update metadata"}}},"example":{"role":"manager","permissions":["read:all","write:team","manage:users"],"metadata":{"updatedBy":"admin@company.com","promotionDate":"2024-02-01"}}}}},"responses":{"200":{"description":"User assignment updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"assignment":{"$ref":"#/components/schemas/UserAssignment"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application or User assignment not found"},"409":{"description":"appUserUuid conflict with existing assignment"}}},"delete":{"summary":"Remove user from application","tags":["Applications - User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Remove a user from an application. Supports both soft delete (deactivate) and hard delete.\n**Required Permission: DELETE** (API Key) **OR** **admin role** (JWT)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for removal","example":"User left the company"},"softDelete":{"type":"boolean","default":true,"description":"Whether to soft delete (deactivate) or hard delete"}}},"example":{"reason":"User role changed - no longer needs access","softDelete":true}}}},"responses":{"200":{"description":"User removed from application successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User assignment deactivated successfully"},"removedAt":{"type":"string","format":"date-time","description":"Timestamp of removal/deactivation"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application or User assignment not found"}}}},"/api/v1/applications/{id}/references":{"get":{"summary":"Check application references","tags":["Applications - Analytics & Reporting"],"security":[{"ApiKeyAuth":[]}],"description":"Check what references this application has and whether it can be safely deleted.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"responses":{"200":{"description":"Application references information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationReferences"}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}}},"/api/v1/applications/{id}/stats":{"get":{"summary":"Get application statistics","tags":["Applications - Analytics & Reporting"],"security":[{"ApiKeyAuth":[]}],"description":"Get detailed statistics for an application.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"timeRange","schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"30d"},"description":"Time range for activity statistics"}],"responses":{"200":{"description":"Application statistics","content":{"application/json":{"schema":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/Application"},"stats":{"$ref":"#/components/schemas/ApplicationStats"},"timeRange":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Application not found"}}}}},"tags":[{"name":"Applications - Core Management","description":"Create, read, update, and delete applications"},{"name":"Applications - Lifecycle","description":"Manage application lifecycle (soft delete, restore, force delete)"},{"name":"Applications - User Management","description":"Manage user assignments to applications"},{"name":"Applications - Analytics & Reporting","description":"Get statistics, references, and usage data"}]}