{"openapi":"3.0.3","info":{"version":"1.0.0","contact":{"name":"API Support","email":"support@contexthub.dev"},"title":"Context Hub API - Complete Documentation","description":"Complete documentation covering all API endpoints in the Context Hub system."},"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","description":"JWT token obtained from an auth provider"}},"schemas":{"Context":{"type":"object","required":["code","data"],"properties":{"code":{"type":"string","description":"Unique code for the context","example":"abc123"},"data":{"type":"object","description":"Context data to store","example":{"user":"john.doe","role":"admin"}}}},"ContextResponse":{"type":"object","properties":{"message":{"type":"string","example":"Context stored"},"code":{"type":"string","example":"abc123"}}},"AuthProvider":{"type":"object","required":["name","issuerUrl"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","readOnly":true},"name":{"type":"string","description":"Unique name for the auth provider","example":"keycloak-prod"},"displayName":{"type":"string","description":"Human-readable name","example":"Keycloak Production"},"issuerUrl":{"type":"string","format":"uri","description":"The issuer URL (iss claim value in JWTs)","example":"https://auth.example.com/realms/master"},"jwksUrl":{"type":"string","format":"uri","description":"URL to the JWKS endpoint for key retrieval","example":"https://auth.example.com/realms/master/protocol/openid-connect/certs"},"publicKeys":{"type":"array","description":"Optional public keys for offline verification (JWK format)","items":{"type":"object","properties":{"kid":{"type":"string","description":"Key ID"},"kty":{"type":"string","description":"Key type (RSA, EC, etc.)"},"n":{"type":"string","description":"Modulus (for RSA keys)"},"e":{"type":"string","description":"Exponent (for RSA keys)"}}}},"clientId":{"type":"string","description":"Client ID for this service","example":"api-service"},"tokenEndpoint":{"type":"string","format":"uri","description":"Token endpoint for authentication","example":"https://auth.example.com/realms/master/protocol/openid-connect/token"},"metadata":{"type":"object","description":"Additional provider-specific metadata"},"isActive":{"type":"boolean","description":"Whether this provider 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}}},"AuthProviderList":{"type":"object","properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/AuthProvider"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"OidcConfiguration":{"type":"object","properties":{"issuerUrl":{"type":"string","format":"uri"},"jwksUrl":{"type":"string","format":"uri"},"tokenEndpoint":{"type":"string","format":"uri"},"authorizationEndpoint":{"type":"string","format":"uri"},"userinfoEndpoint":{"type":"string","format":"uri"},"endSessionEndpoint":{"type":"string","format":"uri"},"supportedScopes":{"type":"array","items":{"type":"string"}},"supportedResponseTypes":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","description":"Full configuration object"}}},"PublicKey":{"type":"object","required":["kid","kty"],"properties":{"kid":{"type":"string","description":"Key ID","example":"key-1"},"kty":{"type":"string","description":"Key type","example":"RSA"},"alg":{"type":"string","description":"Algorithm","example":"RS256"},"use":{"type":"string","description":"Key usage","example":"sig"},"n":{"type":"string","description":"Modulus (for RSA keys)"},"e":{"type":"string","description":"Exponent (for RSA keys)"},"crv":{"type":"string","description":"Curve (for EC keys)"},"x":{"type":"string","description":"X coordinate (for EC keys)"},"y":{"type":"string","description":"Y coordinate (for EC keys)"}}},"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"}}}}},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","readOnly":true},"email":{"type":"string","format":"email","description":"User's email address","example":"user@example.com"},"username":{"type":"string","description":"Unique username","example":"johndoe"},"fullName":{"type":"string","description":"User's full name","example":"John Doe"},"phoneNumber":{"type":"string","description":"User's phone number","example":"+1234567890"},"avatarUrl":{"type":"string","format":"uri","description":"URL to user's avatar image"},"locale":{"type":"string","description":"User's preferred locale","default":"en","example":"en-US"},"timezone":{"type":"string","description":"User's timezone","default":"UTC","example":"America/New_York"},"isActive":{"type":"boolean","description":"Whether the user is active","default":true},"role":{"type":"string","description":"User's role","default":"user","enum":["user","admin","developer","moderator"]},"metadata":{"type":"object","description":"Additional user metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","readOnly":true},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","readOnly":true},"lastLoginAt":{"type":"string","format":"date-time","description":"Last login timestamp","readOnly":true}}},"UserList":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"UserProfile":{"type":"object","allOf":[{"$ref":"#/components/schemas/User"},{"type":"object","properties":{"identities":{"type":"array","description":"User's auth provider identities","items":{"type":"object","properties":{"providerId":{"type":"string"},"providerName":{"type":"string"},"externalUserId":{"type":"string"},"email":{"type":"string"},"isPrimary":{"type":"boolean"}}}},"applications":{"type":"array","description":"User's application profiles","items":{"type":"object","properties":{"applicationId":{"type":"string"},"applicationName":{"type":"string"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}}},"stats":{"type":"object","description":"User statistics (if included)","properties":{"totalApplications":{"type":"integer"},"activeApplications":{"type":"integer"},"totalIdentities":{"type":"integer"},"jwtVerifications":{"type":"integer"},"lastJwtVerification":{"type":"string","format":"date-time"}}}}}]},"UserApplication":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"appUserUuid":{"type":"string","format":"uuid"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BulkAssignmentRequest":{"type":"object","required":["applications"],"properties":{"applications":{"type":"array","items":{"type":"object","required":["applicationId"],"properties":{"applicationId":{"type":"string","format":"uuid"},"appUserUuid":{"type":"string","format":"uuid"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}},"metadata":{"type":"object"}}},"CurrentUserUpdateRequest":{"type":"object","properties":{"fullName":{"type":"string","description":"User's full name"},"phoneNumber":{"type":"string","description":"User's phone number"},"avatarUrl":{"type":"string","format":"uri","description":"URL to user's avatar"},"locale":{"type":"string","description":"User's preferred locale"},"timezone":{"type":"string","description":"User's timezone"},"metadata":{"type":"object","description":"Additional user metadata"}},"example":{"fullName":"John Updated Doe","phoneNumber":"+1987654321","locale":"es-ES","timezone":"Europe/Madrid"}},"ApplicationAssignmentRequest":{"type":"object","properties":{"requestedRole":{"type":"string","default":"user","description":"Requested role (subject to approval)"},"reason":{"type":"string","description":"Reason for requesting access"},"metadata":{"type":"object","description":"Additional request metadata"}},"example":{"requestedRole":"user","reason":"Need access for project collaboration","metadata":{"department":"Engineering","project":"Mobile App"}}},"UserPhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Phase record ID"},"phase":{"type":"string","description":"Current phase name (application-specific)","example":"onboarding"},"active":{"type":"boolean","description":"Whether the phase is active","default":true},"metadata":{"type":"object","description":"Additional phase metadata","example":{"step":3,"completed":"50%"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PhaseUpdateRequest":{"type":"object","required":["phase"],"properties":{"phase":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","maxLength":100,"description":"Phase name (alphanumeric, dashes, underscores only)","example":"profile-setup"},"active":{"type":"boolean","default":true,"description":"Whether the phase is active"},"metadata":{"type":"object","maxProperties":20,"description":"Additional metadata (max 1KB)","example":{"profileComplete":true,"lastStep":"avatar-upload"}}}}},"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/context":{"post":{"summary":"Store context data with a temporary code","tags":["Context"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Store temporary JSON context data that can be retrieved later using the provided code.\nThis endpoint can be authenticated using either:\n- API key with CREATE permission, or\n- Valid JWT token from a configured auth provider (users will be auto-provisioned if needed)\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Context"},"examples":{"userSession":{"summary":"User session context","value":{"code":"session-abc123","data":{"user":{"id":"user-456","email":"user@example.com","role":"admin"},"permissions":["read","write"],"expiresAt":"2024-01-16T00:00:00Z"}}},"simpleData":{"summary":"Simple data context","value":{"code":"temp-data-123","data":{"message":"Hello World","timestamp":"2024-01-15T10:30:00Z"}}}}}}},"responses":{"201":{"description":"Context stored successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextResponse"}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid code: Code is required and must be a non-empty string"}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/context/{code}":{"get":{"summary":"Retrieve context data by code","tags":["Context"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Retrieve temporary context data using the provided code.\nThis endpoint can be authenticated using either:\n- API key with READ permission, or\n- Valid JWT token from a configured auth provider (users will be auto-provisioned if needed)\n\nNote: Depending on configuration, the context may be deleted after retrieval.\n","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"},"description":"The temporary code for the context","example":"abc123"}],"responses":{"200":{"description":"Context data retrieved successfully","content":{"application/json":{"schema":{"type":"object","description":"The stored context data"},"examples":{"userSession":{"summary":"User session data","value":{"user":{"id":"user-456","email":"user@example.com","role":"admin"},"permissions":["read","write"],"expiresAt":"2024-01-16T00:00:00Z"}},"simpleData":{"summary":"Simple data","value":{"message":"Hello World","timestamp":"2024-01-15T10:30:00Z"}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"404":{"description":"Context not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Context not found"}}}}}}}}},"/api/v1/app-logs":{"post":{"summary":"Create a new app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Create a new application log entry.\n**Required Permission: CREATE**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["module","event","payload"],"properties":{"module":{"type":"string","description":"The module/component generating the log"},"event":{"type":"string","description":"Short description of the event"},"payload":{"oneOf":[{"type":"string"},{"type":"object"}],"description":"The log message or data"},"stackTrace":{"type":"string","description":"Stack trace for errors (optional)"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"],"default":"INFO"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code (optional)"},"userId":{"type":"string","description":"Associated user ID (optional)"},"metadata":{"type":"object","description":"Additional key-value data (optional)"}}}}}},"responses":{"201":{"description":"App log created successfully"},"400":{"description":"Invalid input data"},"403":{"$ref":"#/components/responses/PermissionDenied"}}},"get":{"summary":"Get app logs with optional filtering and pagination","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Retrieve application logs with optional filtering and pagination.\n**Required Permission: READ**\n","parameters":[{"in":"query","name":"module","schema":{"type":"string"},"description":"Filter by module name"},{"in":"query","name":"logLevel","schema":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"description":"Filter by log level"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"Filter by user ID"},{"in":"query","name":"event","schema":{"type":"string"},"description":"Search in event names (case-insensitive)"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date-time"},"description":"Filter logs from this date onwards"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date-time"},"description":"Filter logs up to this date"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Number of logs per page"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["createdAt","logLevel","module"],"default":"createdAt"},"description":"Field to order by"},{"in":"query","name":"orderDirection","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Order direction"}],"responses":{"200":{"description":"App logs retrieved successfully"},"400":{"description":"Invalid query parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/{id}":{"get":{"summary":"Get a specific app log by ID","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Retrieve a single application log by its ID.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"responses":{"200":{"description":"App log retrieved successfully"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}},"put":{"summary":"Update an app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Update an existing application log entry.\n**Required Permission: UPDATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"module":{"type":"string"},"event":{"type":"string"},"payload":{"oneOf":[{"type":"string"},{"type":"object"}]},"stackTrace":{"type":"string"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"statusCode":{"type":"integer","minimum":100,"maximum":599},"userId":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"App log updated successfully"},"400":{"description":"Invalid input data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}},"delete":{"summary":"Delete an app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Delete an existing application log entry.\n**Required Permission: DELETE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"responses":{"200":{"description":"App log deleted successfully"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}}},"/api/v1/app-logs/stats":{"get":{"summary":"Get application logs statistics","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Get statistical information about application logs.\n**Required Permission: READ**\n","responses":{"200":{"description":"Log statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalLogs":{"type":"integer"},"logsByLevel":{"type":"object"},"logsByModule":{"type":"object"},"recentActivity":{"type":"object"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/admin/cleanup":{"delete":{"summary":"Admin cleanup of old logs","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Clean up old log entries based on specified criteria.\n**Required Permission: DELETE**\nNote: This is a potentially destructive operation.\n","parameters":[{"in":"query","name":"olderThanDays","schema":{"type":"integer","minimum":1,"default":90},"description":"Delete logs older than this many days"},{"in":"query","name":"logLevel","schema":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"description":"Only delete logs of this level"},{"in":"query","name":"confirm","schema":{"type":"boolean"},"description":"Must be set to true to confirm deletion","required":true}],"responses":{"200":{"description":"Cleanup completed successfully"},"400":{"description":"Missing confirmation or invalid parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/csp-report":{"post":{"summary":"CSP violation report endpoint","tags":["CSP Violations"],"description":"Receives CSP violation reports from browsers and logs them to the app logs system.\nThis endpoint is called automatically by browsers when CSP violations occur.\n","requestBody":{"required":true,"content":{"application/csp-report":{"schema":{"type":"object","properties":{"csp-report":{"type":"object","properties":{"document-uri":{"type":"string","description":"The URI of the document where the violation occurred"},"referrer":{"type":"string","description":"The referrer of the document"},"violated-directive":{"type":"string","description":"The policy directive that was violated"},"original-policy":{"type":"string","description":"The complete CSP policy"},"blocked-uri":{"type":"string","description":"The URI of the resource that was blocked"},"source-file":{"type":"string","description":"The file where the violation occurred"},"line-number":{"type":"integer","description":"The line number where the violation occurred"},"status-code":{"type":"integer","description":"The HTTP status code of the document"}}}}}}}},"responses":{"204":{"description":"CSP violation logged successfully"},"400":{"description":"Invalid CSP report format"}}}},"/api/v1/app-logs/csp-stats":{"get":{"summary":"Get CSP violation statistics","tags":["CSP Violations"],"security":[{"ApiKeyAuth":[]}],"description":"Get statistics and analysis of CSP violations logged in the system.\n**Required Permission: READ**\n","responses":{"200":{"description":"CSP violation statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"totalViolations":{"type":"integer","description":"Total number of CSP violations logged"},"recentViolations":{"type":"integer","description":"Number of recent violations returned"},"stats":{"type":"object","properties":{"violatedDirectives":{"type":"object","description":"Count of violations by directive type"},"blockedUris":{"type":"object","description":"Count of violations by blocked URI"},"sourceFiles":{"type":"object","description":"Count of violations by source file"},"violationsByHour":{"type":"object","description":"Count of violations by hour of day"}}},"logs":{"type":"array","items":{"$ref":"#/components/schemas/AppLog"}}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/admin/keys":{"get":{"summary":"List all API keys","tags":["Admin"],"security":[{"ApiKeyAuth":[]}],"description":"Get information about all API keys in the system.\n**Required Permissions: ALL (CREATE, READ, UPDATE, DELETE)**\n","responses":{"200":{"description":"API keys retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalKeys":{"type":"integer"},"keys":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"keyPreview":{"type":"string","description":"First 8 characters of the key"},"permissions":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"active":{"type":"boolean"},"lastUsed":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"403":{"description":"Insufficient permissions (requires admin access)"}}}},"/api/v1/admin/keys/permissions":{"get":{"summary":"Get available permissions","tags":["Admin"],"security":[{"ApiKeyAuth":[]}],"description":"Get list of all available permissions in the system.\n**Required Permission: READ**\n","responses":{"200":{"description":"Permissions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}}}}}}}},"/api/v1/admin/keys/my-info":{"get":{"summary":"Get information about current API key","tags":["Admin"],"security":[{"ApiKeyAuth":[]}],"description":"Get detailed information about the API key making the request.\n**Required Permission: READ**\n","responses":{"200":{"description":"API key information retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"lastUsed":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/admin/usage/summary":{"get":{"summary":"Get API usage summary","tags":["Admin"],"security":[{"ApiKeyAuth":[]}],"description":"Get summary of API usage across all keys.\n**Required Permission: READ**\n","responses":{"200":{"description":"Usage summary retrieved successfully"}}}},"/api/v1/auth-providers":{"get":{"summary":"List all auth providers","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Get a list of all authentication providers with optional filtering.\n**Required Permission: READ**\n","parameters":[{"in":"query","name":"name","schema":{"type":"string"},"description":"Filter by name"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search in name, display name, or issuer URL"},{"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":10},"description":"Items per page"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["name","createdAt","updatedAt"],"default":"name"},"description":"Field to order by"},{"in":"query","name":"orderDirection","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Order direction"}],"responses":{"200":{"description":"List of auth providers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthProviderList"}}}},"400":{"description":"Invalid query parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}},"post":{"summary":"Create a new auth provider","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Create a new authentication provider.\n**Required Permission: CREATE**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthProvider"}}}},"responses":{"201":{"description":"Auth provider created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"provider":{"$ref":"#/components/schemas/AuthProvider"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"409":{"description":"Auth provider with the same name already exists"}}}},"/api/v1/auth-providers/{id}":{"get":{"summary":"Get auth provider by ID","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Get a single authentication provider by its ID.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"responses":{"200":{"description":"Auth provider details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthProvider"}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"}}},"put":{"summary":"Update an auth provider","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Update an existing authentication provider.\n**Required Permission: UPDATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"issuerUrl":{"type":"string","format":"uri"},"jwksUrl":{"type":"string","format":"uri"},"publicKeys":{"type":"array","items":{"$ref":"#/components/schemas/PublicKey"}},"clientId":{"type":"string"},"tokenEndpoint":{"type":"string","format":"uri"},"metadata":{"type":"object"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Auth provider updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"provider":{"$ref":"#/components/schemas/AuthProvider"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"},"409":{"description":"Auth provider with the same name already exists"}}},"delete":{"summary":"Delete an auth provider","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Delete an authentication provider. This will fail if the provider has associated user identities.\n**Required Permission: DELETE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"responses":{"200":{"description":"Auth provider deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"},"409":{"description":"Cannot delete provider with associated user identities"}}}},"/api/v1/auth-providers/discover":{"post":{"summary":"Discover OIDC configuration","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Discover OpenID Connect configuration from an issuer URL.\n**Required Permission: READ**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["issuerUrl"],"properties":{"issuerUrl":{"type":"string","format":"uri","description":"OIDC issuer URL","example":"https://auth.example.com/realms/master"}}}}}},"responses":{"200":{"description":"OIDC configuration discovered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"configuration":{"$ref":"#/components/schemas/OidcConfiguration"}}}}}},"400":{"description":"Invalid issuer URL or discovery failed"},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/auth-providers/{id}/keys":{"put":{"summary":"Update public keys","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Update or add public keys for offline JWT verification.\n**Required Permission: UPDATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/PublicKey"}}}}}}},"responses":{"200":{"description":"Public keys updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"provider":{"$ref":"#/components/schemas/AuthProvider"}}}}}},"400":{"description":"Invalid request data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"}}}},"/api/v1/auth-providers/{id}/jwks":{"get":{"summary":"Fetch JWKS from provider","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Fetch the current JWKS from the provider's jwksUrl.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"responses":{"200":{"description":"JWKS fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"jwks":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/PublicKey"}}}},"provider":{"$ref":"#/components/schemas/AuthProvider"}}}}}},"400":{"description":"Provider does not have a JWKS URL"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"},"502":{"description":"Failed to fetch JWKS from provider"}}}},"/api/v1/auth-providers/{id}/stats":{"get":{"summary":"Get auth provider statistics","tags":["Auth Providers"],"security":[{"ApiKeyAuth":[]}],"description":"Get statistics for an auth provider, including usage counts.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Auth provider ID"}],"responses":{"200":{"description":"Statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/AuthProvider"},"stats":{"type":"object","properties":{"identityCount":{"type":"integer","description":"Number of user identities with this provider"},"userCount":{"type":"integer","description":"Number of unique users with this provider"},"auditCount":{"type":"integer","description":"Number of JWT verification audit entries"},"successfulVerifications":{"type":"integer","description":"Number of successful JWT verifications"},"failedVerifications":{"type":"integer","description":"Number of failed JWT verifications"},"verificationSuccessRate":{"type":"string","description":"Success rate percentage"},"recentJwtAudits":{"type":"array","description":"Recent JWT verification audits","items":{"type":"object"}}}}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"Auth provider not found"}}}},"/api/v1/auth-providers/jwt/verify":{"post":{"summary":"Verify a JWT token","tags":["JWT"],"security":[{"ApiKeyAuth":[]}],"description":"Verifies a JWT token against the configured auth providers.\nReturns information about the token and its claims if valid.\n**Required Permission: READ**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The JWT token to verify"},"audience":{"type":"string","description":"Optional audience to verify against"}}}}}},"responses":{"200":{"description":"Token verified successfully","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the token is valid"},"payload":{"type":"object","description":"The token payload"},"provider":{"type":"object","description":"Information about the auth provider"},"user":{"type":"object","description":"User information if the subject is found"}}}}}},"400":{"description":"Invalid token format or missing token"},"401":{"description":"Token verification failed"},"403":{"description":"Invalid API key or insufficient permissions"}}}},"/api/v1/auth-providers/jwt/decode":{"post":{"summary":"Decode a JWT token without verification","tags":["JWT"],"security":[{"ApiKeyAuth":[]}],"description":"Decodes a JWT token without verifying its signature.\nThis endpoint only parses the token and returns its contents.\n**Required Permission: READ**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The JWT token to decode"}}}}}},"responses":{"200":{"description":"Token decoded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"header":{"type":"object","description":"The token header"},"payload":{"type":"object","description":"The token payload"}}}}}},"400":{"description":"Invalid token format or missing token"},"403":{"description":"Invalid API key or insufficient permissions"}}}},"/api/v1/auth-providers/jwt/whoami":{"get":{"summary":"Get current user information from JWT token","tags":["JWT"],"security":[{"BearerAuth":[]}],"description":"Returns information about the authenticated user based on the JWT token.\nThis endpoint requires JWT authentication.\n","responses":{"200":{"description":"User information retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"username":{"type":"string"},"role":{"type":"string"}}},"token":{"type":"object","description":"Summary of the token claims"},"identities":{"type":"array","description":"Auth provider identities for this user"}}}}}},"401":{"description":"JWT authentication required"}}}},"/api/v1/auth-providers/jwt/test-auth":{"get":{"summary":"Test endpoint supporting both JWT and API key auth","tags":["JWT"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"This endpoint can be accessed with either JWT token or API key.\nIt returns information about how the authentication was performed.\n","responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"authMethod":{"type":"string","enum":["jwt","apiKey","both"]},"authInfo":{"type":"object"}}}}}},"401":{"description":"Authentication required"},"403":{"description":"Invalid credentials or insufficient permissions"}}}},"/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"}}}},"/api/v1/users/me":{"get":{"summary":"Get my profile","tags":["Current User"],"security":[{"BearerAuth":[]}],"description":"Get the profile of the currently authenticated user.\n\n**Authentication:** JWT token required\n","parameters":[{"in":"query","name":"includeApplications","schema":{"type":"boolean","default":true},"description":"Include user's application profiles"},{"in":"query","name":"includeIdentities","schema":{"type":"boolean","default":true},"description":"Include auth provider identities"},{"in":"query","name":"includeStats","schema":{"type":"boolean","default":false},"description":"Include user statistics"}],"responses":{"200":{"description":"Current user's profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"description":"JWT authentication required"}}},"put":{"summary":"Update current user's profile","tags":["Current User"],"security":[{"BearerAuth":[]}],"description":"Update the profile of the currently authenticated user.\nOnly certain fields can be updated by the user themselves.\n**JWT authentication required**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","description":"User's full name"},"phoneNumber":{"type":"string","description":"User's phone number"},"avatarUrl":{"type":"string","format":"uri","description":"URL to user's avatar"},"locale":{"type":"string","description":"User's preferred locale"},"timezone":{"type":"string","description":"User's timezone"},"metadata":{"type":"object","description":"Additional user metadata"}}},"example":{"fullName":"John Updated Doe","phoneNumber":"+1987654321","avatarUrl":"https://example.com/avatar.jpg","locale":"es-ES","timezone":"Europe/Madrid","metadata":{"preferences":{"theme":"dark","notifications":true}}}}}},"responses":{"200":{"description":"Profile updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"user":{"$ref":"#/components/schemas/User"}}}}}},"400":{"description":"Invalid request data or restricted fields"},"401":{"description":"JWT authentication required"}}}},"/api/v1/users/me/applications":{"get":{"summary":"Get my applications","tags":["Current User"],"security":[{"BearerAuth":[]}],"description":"Get a list of applications that you are assigned to.\n\n**Authentication:** JWT token required\n","parameters":[{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"includePermissions","schema":{"type":"boolean","default":true},"description":"Include permissions array"},{"in":"query","name":"includePhases","schema":{"type":"boolean","default":true},"description":"Include user phases"},{"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"}],"responses":{"200":{"description":"Your application assignments","content":{"application/json":{"schema":{"type":"object","properties":{"applications":{"type":"array","items":{"type":"object","properties":{"applicationId":{"type":"string","format":"uuid"},"applicationName":{"type":"string"},"displayName":{"type":"string"},"appUserUuid":{"type":"string","format":"uuid"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"phases":{"type":"array","items":{"type":"object","properties":{"phase":{"type":"string"},"active":{"type":"boolean"}}}}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"JWT authentication required"}}}},"/api/v1/users/me/applications/{applicationId}":{"post":{"summary":"Request access to application","tags":["Current User"],"security":[{"BearerAuth":[]}],"description":"Request assignment to an application. This is a self-service endpoint where you\ncan request access to applications. The assignment may be auto-approved or require\nadmin approval based on application configuration.\n\n**Authentication:** JWT token required\n","parameters":[{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID to request assignment to"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationAssignmentRequest"}}}},"responses":{"201":{"description":"Assignment request processed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Application assignment completed"},"assignment":{"type":"object","properties":{"applicationId":{"type":"string","format":"uuid"},"appUserUuid":{"type":"string","format":"uuid"},"role":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"status":{"type":"string","enum":["approved","pending","rejected"],"description":"Assignment status"}}}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"JWT authentication required"},"404":{"description":"Application not found"},"409":{"description":"You are already assigned to this application"}}}},"/api/v1/users":{"get":{"summary":"List all users","tags":["User Management"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Get a list of all users with optional filtering and pagination.\n\n**Authentication:**\n- API Key with READ permission\n- JWT token with admin role\n","parameters":[{"in":"query","name":"email","schema":{"type":"string"},"description":"Filter by email address"},{"in":"query","name":"username","schema":{"type":"string"},"description":"Filter by username"},{"in":"query","name":"role","schema":{"type":"string","enum":["user","admin","developer","moderator"]},"description":"Filter by user role"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search in email, username, or full name"},{"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":["email","username","fullName","createdAt","updatedAt","lastLoginAt"],"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":"includeStats","schema":{"type":"boolean","default":false},"description":"Include user statistics"},{"in":"query","name":"includeIdentities","schema":{"type":"boolean","default":false},"description":"Include auth provider identities"}],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserList"}}}},"400":{"description":"Invalid query parameters"},"403":{"description":"Insufficient permissions"}}},"post":{"summary":"Create a new user","tags":["User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Create a new user in the system. This endpoint is primarily for API key access.\n\n**Note:** This endpoint does not handle password creation. Passwords are managed\nthrough the configured auth providers (Keycloak/Cognito).\n\n**API Key Required Permission: CREATE**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"User's email address (must be unique)","example":"john.doe@example.com"},"username":{"type":"string","description":"Unique username (optional, must be unique if provided)","example":"johndoe"},"fullName":{"type":"string","description":"User's full name","example":"John Doe"},"phoneNumber":{"type":"string","description":"User's phone number (including country code)","example":"+1234567890"},"avatarUrl":{"type":"string","format":"uri","description":"URL to user's avatar image","example":"https://example.com/avatars/johndoe.jpg"},"locale":{"type":"string","default":"en","description":"User's preferred locale (e.g., en-US, es-ES, fr-FR)","example":"en-US"},"timezone":{"type":"string","default":"UTC","description":"User's timezone (IANA timezone format)","example":"America/New_York"},"isActive":{"type":"boolean","default":true,"description":"Whether the user account is active","example":true},"role":{"type":"string","default":"user","enum":["user","admin","developer","moderator"],"description":"User's system role:\n- `user`: Standard user access\n- `admin`: Full administrative access\n- `developer`: Developer access with API capabilities\n- `moderator`: Moderation capabilities\n","example":"user"},"metadata":{"type":"object","description":"Additional custom metadata for the user (free-form JSON object)","additionalProperties":true,"example":{"department":"Engineering","employeeId":"EMP-12345","office":"San Francisco","skills":["JavaScript","Python","React"]}}}},"examples":{"minimal":{"summary":"Minimal user (only required fields)","value":{"email":"minimal@example.com"}},"typical":{"summary":"Typical user registration","value":{"email":"john.doe@example.com","username":"johndoe","fullName":"John Doe","role":"user","locale":"en-US","timezone":"America/New_York"}},"complete":{"summary":"Complete user with all fields","value":{"email":"jane.smith@example.com","username":"janesmith","fullName":"Jane Smith","phoneNumber":"+14155552671","avatarUrl":"https://example.com/avatars/janesmith.jpg","locale":"en-GB","timezone":"Europe/London","isActive":true,"role":"developer","metadata":{"department":"Engineering","employeeId":"EMP-98765","office":"London","team":"Platform","startDate":"2024-01-15"}}}}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User created successfully"},"user":{"$ref":"#/components/schemas/User"}}},"example":{"message":"User created successfully","user":{"id":"550e8400-e29b-41d4-a716-446655440000","email":"john.doe@example.com","username":"johndoe","fullName":"John Doe","phoneNumber":"+1234567890","avatarUrl":"https://example.com/avatars/johndoe.jpg","locale":"en-US","timezone":"America/New_York","isActive":true,"role":"user","metadata":{"department":"Engineering"},"createdAt":"2024-06-12T10:30:00Z","updatedAt":"2024-06-12T10:30:00Z","lastLoginAt":null}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"examples":{"missingEmail":{"summary":"Missing required email","value":{"error":"Email is required"}},"invalidEmail":{"summary":"Invalid email format","value":{"error":"Invalid email format"}},"invalidUsername":{"summary":"Invalid username","value":{"error":"Invalid username: Must be a non-empty string"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"},"409":{"description":"User with the same email or username already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"examples":{"emailExists":{"summary":"Email already exists","value":{"error":"User with email 'john.doe@example.com' already exists"}},"usernameExists":{"summary":"Username already exists","value":{"error":"User with username 'johndoe' already exists"}}}}}}}}},"/api/v1/users/{id}":{"get":{"summary":"Get user by ID","tags":["User Management"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Get a single user by their ID.\n\n**Authentication:**\n- API Key with READ permission\n- JWT token (users can only access their own profile unless admin)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"},{"in":"query","name":"includeApplications","schema":{"type":"boolean","default":false},"description":"Include user's application profiles"},{"in":"query","name":"includeIdentities","schema":{"type":"boolean","default":false},"description":"Include auth provider identities"}],"responses":{"200":{"description":"User details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"403":{"description":"Access denied (JWT users can only access own profile)"},"404":{"description":"User not found"}}},"put":{"summary":"Update a user","tags":["User Management"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Update an existing user.\n\n**Authentication:**\n- API Key with UPDATE permission\n- JWT token (users can only update their own profile unless admin)\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","description":"User's full name"},"phoneNumber":{"type":"string","description":"User's phone number"},"avatarUrl":{"type":"string","format":"uri","description":"URL to user's avatar"},"locale":{"type":"string","description":"User's preferred locale"},"timezone":{"type":"string","description":"User's timezone"},"metadata":{"type":"object","description":"Additional user metadata"}}},"example":{"fullName":"John Updated Doe","phoneNumber":"+1987654321","avatarUrl":"https://example.com/avatar.jpg","locale":"es-ES","timezone":"Europe/Madrid","metadata":{"preferences":{"theme":"dark","notifications":true}}}}}},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User updated successfully"},"user":{"$ref":"#/components/schemas/User"}}}}}},"400":{"description":"Invalid request data"},"403":{"description":"Access denied"},"404":{"description":"User not found"},"409":{"description":"Email/username already exists"}}},"delete":{"summary":"Delete a user","tags":["User Management"],"security":[{"ApiKeyAuth":[]}],"description":"Delete a user (soft delete).\n\n**Authentication:** API Key with DELETE permission\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"responses":{"200":{"description":"User deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User deleted successfully"},"deletedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"User not found"},"409":{"description":"Cannot delete user (has active references)"}}}},"/api/v1/users/{userId}/applications":{"get":{"summary":"Get user's applications","tags":["User Applications"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Get all applications assigned to a specific user.\n\n**Authentication:**\n- API Key with READ permission\n- JWT token with admin role\n","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"},{"in":"query","name":"isActive","schema":{"type":"boolean"},"description":"Filter by active status"},{"in":"query","name":"role","schema":{"type":"string"},"description":"Filter by role"},{"in":"query","name":"includePermissions","schema":{"type":"boolean","default":true},"description":"Include permissions array"},{"in":"query","name":"includePhases","schema":{"type":"boolean","default":false},"description":"Include user phases"},{"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":"User's application assignments","content":{"application/json":{"schema":{"type":"object","properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/UserApplication"}},"pagination":{"type":"object"}}}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"User not found"}}}},"/api/v1/users/{userId}/applications/{applicationId}":{"put":{"summary":"Update user's application assignment","tags":["User Applications"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Update a user's application assignment.\n\n**Authentication:**\n- API Key with UPDATE permission\n- JWT token (users can update limited fields on their own assignments, admins can update all)\n","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"},{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","description":"User's role in the application (admin only)"},"permissions":{"type":"array","items":{"type":"string"},"description":"User's permissions (admin only)"},"isActive":{"type":"boolean","description":"Whether the assignment is active (admin only)"},"metadata":{"type":"object","description":"Assignment metadata (users can update this)"}}},"example":{"role":"admin","permissions":["read","write","delete"],"metadata":{"notes":"Promoted to admin role"}}}}},"responses":{"200":{"description":"Assignment updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User assignment updated successfully"},"assignment":{"$ref":"#/components/schemas/UserApplication"}}}}}},"400":{"description":"Invalid request data"},"403":{"description":"Insufficient permissions"},"404":{"description":"User assignment not found"},"409":{"description":"Conflict (e.g., UUID already exists)"}}},"delete":{"summary":"Remove user from application","tags":["User Applications"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Remove a user from an application.\n\n**Authentication:**\n- API Key with DELETE permission\n- JWT token with admin role\n","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"},{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"},{"in":"query","name":"reason","schema":{"type":"string"},"description":"Reason for removal"},{"in":"query","name":"softDelete","schema":{"type":"boolean","default":true},"description":"Whether to soft delete (mark inactive) or hard delete"}],"responses":{"200":{"description":"User removed from application successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"User assignment deactivated successfully"},"result":{"type":"object"}}}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"User assignment not found"}}}},"/api/v1/users/{userId}/applications/bulk":{"post":{"summary":"Bulk assign user to applications","tags":["User Applications"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Assign a user to multiple applications in a single request.\n\n**Authentication:**\n- API Key with CREATE permission\n- JWT token with admin role\n","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAssignmentRequest"},"example":{"applications":[{"applicationId":"app-123-uuid","role":"user","permissions":["read","write"]},{"applicationId":"app-456-uuid","appUserUuid":"custom-uuid-789","role":"admin","permissions":["read","write","delete"]}],"metadata":{"bulkAssignedBy":"admin@example.com","reason":"New employee onboarding"}}}}},"responses":{"201":{"description":"Bulk assignment completed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Bulk assignment completed"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total applications to assign"},"successful":{"type":"array","items":{"type":"object","properties":{"applicationId":{"type":"string"},"appUserUuid":{"type":"string"},"assignment":{"$ref":"#/components/schemas/UserApplication"}}}},"failed":{"type":"array","items":{"type":"object","properties":{"applicationId":{"type":"string"},"error":{"type":"string"}}}}}}}}}}},"400":{"description":"Invalid request data"},"403":{"description":"Insufficient permissions"},"404":{"description":"User not found"}}}},"/api/v1/users/password/confirm":{"post":{"summary":"Confirm password reset with token","tags":["Password Management"],"description":"Complete the password reset process using a reset token.\nThis endpoint does not require authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","newPassword"],"properties":{"token":{"type":"string","description":"Password reset token from email"},"newPassword":{"type":"string","format":"password","description":"New password. Must meet the following requirements:\n- At least 8 characters long\n- Contains at least one lowercase letter\n- Contains at least one uppercase letter\n- Contains at least one number\n- Contains at least one special character\n"}}},"example":{"token":"abc123def456...","newPassword":"MyNewSecurePass123!"}}}},"responses":{"200":{"description":"Password reset successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Password has been reset successfully"}}}},"400":{"description":"Invalid token or password validation failed"},"404":{"description":"Token not found or expired"}}}},"/api/v1/users/me/password":{"put":{"summary":"Change current user's password","tags":["Password Management"],"security":[{"BearerAuth":[]}],"description":"Change the password for the currently authenticated user.\nRequires JWT authentication and validates the current password.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","format":"password","description":"Current password for verification"},"newPassword":{"type":"string","format":"password","description":"New password. Must meet the following requirements:\n- At least 8 characters long\n- Contains at least one lowercase letter\n- Contains at least one uppercase letter\n- Contains at least one number\n- Contains at least one special character\n- No spaces allowed\n- Must be different from current password\n"}}},"example":{"currentPassword":"MyCurrentPass123!","newPassword":"MyNewSecurePass456!"}}}},"responses":{"200":{"description":"Password changed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"Password changed successfully"}}}},"400":{"description":"Invalid request or password validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"JWT authentication required"},"404":{"description":"User not found or not properly configured"}}}},"/api/v1/users/password":{"post":{"summary":"Request password reset (Public)","tags":["Password Management"],"description":"Request a password reset link to be sent to the user's email.\nThis endpoint does not require authentication.\nFor security reasons, it always returns success even if the email doesn't exist.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address of the user requesting password reset"}}},"example":{"email":"user@example.com"}}}},"responses":{"200":{"description":"Password reset initiated (always returns success for security)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"example":{"success":true,"message":"If the email exists in our system, a password reset link has been sent."}}}},"400":{"description":"Invalid email format"}}}},"/api/v1/users/{id}/password":{"put":{"summary":"Admin reset user password","tags":["Password Management"],"security":[{"ApiKeyAuth":[]}],"description":"Reset a user's password administratively. This endpoint requires API key\nauthentication with UPDATE permission. The auth provider used will be the\none configured in the environment variables.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"User ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPassword"],"properties":{"newPassword":{"type":"string","format":"password","description":"New password for the user. If temporary is false, must meet\nstandard password requirements.\n"},"temporary":{"type":"boolean","default":false,"description":"Whether the password should be marked as temporary,\nrequiring the user to change it on next login\n"}}},"example":{"newPassword":"TempPassword123!","temporary":true}}}},"responses":{"200":{"description":"Password reset successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"temporary":{"type":"boolean"}}},"example":{"success":true,"message":"Password temporarily reset successfully","temporary":true}}}},"400":{"description":"Invalid request or user configuration error"},"403":{"description":"Insufficient permissions (UPDATE required)"},"404":{"description":"User not found"},"503":{"description":"No auth provider is properly configured"}}}},"/api/v1/users/me/applications/{applicationId}/phase":{"post":{"summary":"Update or create user's phase for an application","tags":["User Phases"],"security":[{"BearerAuth":[]}],"description":"Sets or updates the current phase for a user in a specific application.\nThis endpoint performs an \"upsert\" operation - creates if not exists, updates if exists.\nOnly one phase per user-application is maintained.\n\n**Note**: If the user is not already assigned to the application, they will be \nautomatically assigned with default 'user' role and 'read' permissions when \nsetting a phase.\n\n**JWT authentication required**\n","parameters":[{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhaseUpdateRequest"},"examples":{"onboarding":{"summary":"User in onboarding","value":{"phase":"onboarding","active":true,"metadata":{"step":2,"completed":"40%"}}},"active-user":{"summary":"Active user","value":{"phase":"active-user","active":true}},"checkout":{"summary":"E-commerce checkout","value":{"phase":"checkout","active":true,"metadata":{"step":"payment","cartValue":99.99}}}}}}},"responses":{"200":{"description":"Phase updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"phase":{"$ref":"#/components/schemas/UserPhase"}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"JWT authentication required"},"404":{"description":"Application not found or not active"}}},"get":{"summary":"Get user's current phase for an application","tags":["User Phases"],"security":[{"BearerAuth":[]}],"description":"Retrieves the current phase for a user in a specific application.\n**JWT authentication required**\n","parameters":[{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"responses":{"200":{"description":"Phase retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"phase":{"$ref":"#/components/schemas/UserPhase"}}}}}},"401":{"description":"JWT authentication required"},"404":{"description":"No phase set, user not assigned to application, or application not found"}}},"delete":{"summary":"Delete user's phase for an application","tags":["User Phases"],"security":[{"BearerAuth":[]}],"description":"Removes the current phase for a user in a specific application.\nThis resets the user to having no phase in the application.\n**JWT authentication required**\n","parameters":[{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"responses":{"200":{"description":"Phase deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"JWT authentication required"},"404":{"description":"No phase to delete or user not assigned to application"}}}},"/api/v1/applications/{applicationId}/phase-stats":{"get":{"summary":"Get phase statistics for an application (Admin)","tags":["User Phases"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"description":"Retrieves phase distribution and statistics for an application.\n**Required Permission: READ (or admin role for JWT)**\n","parameters":[{"in":"path","name":"applicationId","required":true,"schema":{"type":"string","format":"uuid"},"description":"Application ID"}],"responses":{"200":{"description":"Phase statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"stats":{"type":"object","properties":{"applicationId":{"type":"string"},"applicationName":{"type":"string"},"totalUsers":{"type":"integer"},"usersWithPhases":{"type":"integer"},"usersWithoutPhases":{"type":"integer"},"totalPhases":{"type":"integer"},"activePhases":{"type":"integer"},"phaseDistribution":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"activeCount":{"type":"integer"},"users":{"type":"array","items":{"type":"object"}}}}},"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"Application not found"}}}}},"tags":[{"name":"App Logs","description":"Application functional logging - Track events, errors, and system activities"},{"name":"CSP Violations","description":"Content Security Policy violation reporting and analysis"},{"name":"Admin","description":"Administrative endpoints for key management and system information"},{"name":"Auth Providers","description":"Management of authentication providers"},{"name":"JWT","description":"JWT token verification and testing endpoints"},{"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"},{"name":"Current User","description":"Endpoints for the currently authenticated user (JWT required)"},{"name":"User Management","description":"User administration endpoints (Admin/API Key access)"},{"name":"User Applications","description":"User-application assignment management"},{"name":"Password Management","description":"Password management endpoints"},{"name":"User Phases","description":"User application phase management endpoints"}]}