{"openapi":"3.0.3","info":{"version":"1.0.0","contact":{"name":"API Support","email":"support@contexthub.dev"},"title":"Context Hub - Users API","description":"User management system with role-based access control, profile management, and application phase tracking."},"servers":[{"url":"http://localhost:3000","description":"Development Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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"}}}}}},"paths":{"/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":"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"}]}