{"openapi":"3.0.0","info":{"title":"20North API","version":"1.0.0","description":"RBAC + backend system APIs"},"servers":[{"url":"http://localhost:5000","description":"Local server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Auth"},{"name":"Roles"},{"name":"Permissions"},{"name":"Users"},{"name":"Charity"}],"paths":{"/api/auth/signup":{"post":{"tags":["Auth"],"summary":"Signup user","description":"This API is used to create a new user account in the system.\n\nOnly authorized users with **USER_MANAGEMENT CREATE** permission can access this endpoint.\n\nThe API allows creation of users such as Charity, Casino, Donor, or other platform users by assigning a valid **roleId** and **organizationId**.\n\n**Required fields:**\n* **name**\n* **email**\n* **organizationId**\n\n**Optional fields:**\n* **phone**\n* **roleId**\n* **address1**\n* **address2**\n* **city**\n* **state**\n* **zipCode**\n\n**Validation Rules:**\n* **email** must be unique and valid\n* **organizationId** must exist\n* **roleId** must be a valid role\n* **name** cannot be empty\n\n**On successful creation:**\n* User record is created\n* User can later login using assigned credentials\n* Default status is **ACTIVE** unless configured otherwise\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","organizationId","roleId"],"properties":{"name":{"type":"string","example":"James Anderson"},"email":{"type":"string","example":"james.anderson@example.com"},"organizationId":{"type":"integer","example":1},"phone":{"type":"string","example":"2025550101"},"roleId":{"type":"integer","example":5},"address1":{"type":"string","example":"742 Evergreen Terrace"},"address2":{"type":"string","example":"Suite 12A"},"city":{"type":"string","example":"New York"},"state":{"type":"string","example":"New York"},"zipCode":{"type":"string","example":"10001"}}}}}},"responses":{"201":{"description":"User created successfully"},"400":{"description":"Validation error"},"500":{"description":"Internal server error"}}}},"/api/auth/login":{"post":{"tags":["Auth"],"summary":"Login user","description":"This API is used to authenticate a user into the system.\n\nUsers can login using a valid email and password combination.\n\nOn successful authentication:\n* Access token is returned\n* Refresh token is returned\n* User details are returned\n* User session becomes active\n\n**Required fields:**\n* **email**\n* **password**\n\n**Validation Rules:**\n* Email must exist in the system\n* Password must be correct\n* User account must be active\n\n**Supported roles:**\n* SUPER_ADMIN\n* CHARITY\n* CASINO\n* DONOR\n* Other platform users\n\n**Authentication Response Includes:**\n* JWT access token\n* JWT refresh token\n* User profile information\n* Role details\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"superadmin_20north@maildropdm312.chetu.com"},"password":{"type":"string","format":"password","example":"Admin@123"}}},"examples":{"superAdmin":{"summary":"Super Admin Login","value":{"email":"superadmin_20north@maildropdm312.chetu.com","password":"Admin@123"}},"charity":{"summary":"Charity Login","value":{"email":"charity@mail.com","password":"Charity@123"}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"accessToken":{"type":"string","example":"jwt-access-token"},"refreshToken":{"type":"string","example":"jwt-refresh-token"},"user":{"type":"object","properties":{"id":{"type":"string","example":"clx123"},"name":{"type":"string","example":"Super Admin"},"email":{"type":"string","example":"admin@20north.com"},"role":{"type":"string","example":"SUPER_ADMIN"}}}}}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid email or password"}}}}}},"500":{"description":"Internal server error"}}}},"/api/auth/logout":{"post":{"tags":["Auth"],"summary":"Logout user","description":"This API is used to logout the currently authenticated user.\n\nOn successful logout:\n* Access token becomes invalid on frontend\n* Refresh token cookie is cleared\n* User session is terminated\n\n**Security:**\n* Requires valid authentication token\n","responses":{"200":{"description":"Logged out"}}}},"/api/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh token","description":"This API is used to refresh the JWT access token.\n\nOn successful validation:\n* New access token is generated\n* User session continues without re-login\n\n**Security:**\n* Requires valid refresh token\n","responses":{"200":{"description":"Token refreshed"}}}},"/api/auth/forgot-password":{"post":{"tags":["Auth"],"summary":"Forgot password","description":"This API is used to initiate the forgot password process.\n\nThe system sends an OTP or reset link to the registered email address.\n\n**Required fields:**\n* **email**\n\n**Validation Rules:**\n* Email must exist in the system\n* User account must be active\n\n**On success:**\n* OTP is generated\n* Reset instructions are sent\n","responses":{"200":{"description":"OTP sent"}}}},"/api/auth/validate-otp":{"post":{"tags":["Auth"],"summary":"Validate OTP","description":"This API validates the OTP sent during password reset flow.\n\n**Required fields:**\n* **email**\n* **otp**\n\n**Validation Rules:**\n* OTP must be valid\n* OTP must not be expired\n\n**On success:**\n* User is allowed to reset password\n","responses":{"200":{"description":"OTP validated"}}}},"/api/auth/reset-password":{"post":{"tags":["Auth"],"summary":"Reset password","description":"This API is used to reset the user's password.\n\n**Required fields:**\n* **email**\n* **otp**\n* **newPassword**\n\n**Validation Rules:**\n* OTP must be valid\n* OTP must not be expired\n* New password must meet security requirements\n\n**On success:**\n* User's password is updated\n","responses":{"200":{"description":"Password reset"}}}},"/api/role":{"get":{"tags":["Roles"],"summary":"Get all roles","description":"This API retrieves all available roles in the system.\n\nRoles are used for RBAC (Role Based Access Control).\n\n**Security:**\n* Requires authentication\n* User must have permission to view roles\n\n**Response Includes:**\n* Role ID\n* Role name\n* Description\n* Created date\n","responses":{"200":{"description":"Success"}}},"post":{"tags":["Roles"],"summary":"Create role","description":"This API is used to create a new role in the system.\n\nRoles define user access permissions.\n\n**Required fields:**\n* **name**\n\n**Optional fields:**\n* **description**\n\n**Validation Rules:**\n* Role name must be unique\n* Role name cannot be empty\n\n**On success:**\n* New role is created\n* Role becomes available for permission assignment\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Role created"}}}},"/api/role/{id}":{"get":{"tags":["Roles"],"summary":"Get role by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success"}}},"put":{"tags":["Roles"],"summary":"Update role","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Updated"}}},"delete":{"tags":["Roles"],"summary":"Delete role","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/permissions":{"get":{"tags":["Permissions"],"summary":"Get all permissions","description":"This API assigns permissions to a specific role.\n\nPermissions control access to modules and actions in the platform.\n\n**Required fields:**\n* **roleId**\n* **permissionIds**\n\n**Validation Rules:**\n* Role must exist\n* Permission IDs must be valid\n\n**On success:**\n* Permissions are linked to the role\n* Updated permissions apply immediately\n","responses":{"200":{"description":"Success"}}}},"/api/permissions/grouped":{"get":{"tags":["Permissions"],"summary":"Get grouped permissions","responses":{"200":{"description":"Success"}}}},"/api/permissions/asign-permission":{"post":{"tags":["Permissions"],"summary":"Assign permissions to role","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["roleId","permissionIds"],"properties":{"roleId":{"type":"integer"},"permissionIds":{"type":"array","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Assigned"}}}},"/api/users":{"get":{"tags":["Users"],"summary":"Get all users","description":"This API retrieves all users from the system.\n\nSupports searching, filtering, pagination, and sorting.\n\n**Security:**\n* Requires authentication\n* Requires user management permission\n\n**Response Includes:**\n* User profile details\n* Role information\n* Organization details\n* Account status\n","responses":{"200":{"description":"Success"}}}},"/api/users/{id}":{"get":{"tags":["Users"],"summary":"Get user by ID","description":"This API retrieves detailed information for a specific user.\n\n**Path Parameter:**\n* **id** - User ID\n\n**Security:**\n* Requires authentication\n\n**Response Includes:**\n* Basic profile details\n* Role information\n* Contact information\n* Account status\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success"}}},"delete":{"tags":["Users"],"summary":"Delete user","description":"This API deletes or deactivates a user account.\n\n**Path Parameter:**\n* **id** - User ID\n\n**Security:**\n* Requires authentication\n* Requires delete permission\n\n**On success:**\n* User account is removed or marked deleted\n* User can no longer login\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/users/profile":{"get":{"tags":["Users"],"summary":"Get user profile","description":"This API retrieves the currently authenticated user's profile information.\n\n**Security:**\n* Requires valid authentication token\n\n**Response Includes:**\n* User details\n* Contact information\n* Role information\n* Profile image\n","responses":{"200":{"description":"Success"}}},"put":{"tags":["Users"],"summary":"Update profile","description":"This API updates the profile information of the authenticated user.\n\nSupports multipart form data for profile image upload.\n\n**Optional fields:**\n* Profile image\n* Contact details\n* Address details\n\n**Security:**\n* Requires authentication\n\n**On success:**\n* User profile is updated\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Updated"}}}},"/api/charity/invite":{"post":{"tags":["Charity"],"summary":"Create a charity invitation","description":"This API sends a charity invitation to a user's email.\n\nThe invited user receives a registration link.\n\n**Required fields:**\n* **email**\n* **charityName**\n\n**Validation Rules:**\n* Email must be unique\n* Charity name cannot be empty\n\n**On success:**\n* Invitation email is sent\n* Invitation token is generated\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","charityName"],"properties":{"email":{"type":"string"},"charityName":{"type":"string"}}}}}},"responses":{"200":{"description":"Invitation sent successfully"}}}},"/api/charity/register":{"post":{"tags":["Charity"],"summary":"Register from an invite link","description":"This API completes charity registration using an invitation token.\n\n**Required fields:**\n* **inviteToken**\n* **password**\n\n**Validation Rules:**\n* Invite token must be valid\n* Invite token must not be expired\n* Password must meet security rules\n\n**On success:**\n* Charity account is activated\n* User can login\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inviteToken","password"],"properties":{"inviteToken":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"201":{"description":"Charity registered"}}}},"/api/charity/get-all-charity":{"get":{"tags":["Charity"],"summary":"Get all charities","description":"This API retrieves a list of all charities.\nSupports:\n* Pagination\n* Searching\n* Sorting\n* Status filtering\n* Date filtering\n\n**Security:**\n* Requires authentication\n\n**Response Includes:**\n* Charity details\n* Owner details\n* Donation statistics\n* Casino count\n* Status information\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of charities","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"impersonating":{"type":"boolean"}}}}}}}}},"/api/charity/get-charity-by-id/{id}":{"get":{"tags":["Charity"],"summary":"Get charity by ID","description":"description: |\nThis API retrieves detailed information about a specific charity.\n\n**Path Parameter:**\n* **id** - Charity ID\n\n**Security:**\n* Requires authentication\n\n**Response Includes:**\n* Charity information\n* Owner details\n* Donation details\n* Status information\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/charity/approve/{charityId}":{"patch":{"tags":["Charity"],"summary":"Approve or change charity status","description":"This API updates the approval status of a charity.\n\n**Supported Status Values:**\n* approved\n* rejected\n* pending\n\n**Security:**\n* Requires authentication\n* Requires approval permission\n\n**On success:**\n* Charity status is updated\n* Related workflows may trigger\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"charityId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected","pending"]}}}}}},"responses":{"200":{"description":"Status updated"}}}},"/api/auth/impersonate/{targetUserId}":{"post":{"tags":["Auth"],"summary":"Impersonate a user","description":"This API allows authorized admins to login as another user without using their password.\n\nA new access token and refresh token are generated for the impersonated session.\n\n**Path Parameter:**\n* **targetUserId**\n\n**Security:**\n* Requires impersonation permission\n\n**On success:**\n* Impersonation session starts\n* Tokens are replaced\n* Actions are performed as target user\n\n**Important:**\n* Original admin identity is still tracked internally\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"targetUserId","in":"path","required":true,"description":"The ID of the user you want to impersonate","schema":{"type":"string"}}],"responses":{"200":{"description":"Impersonation successful","headers":{"Set-Cookie":{"description":"Sets the refresh token in an HttpOnly cookie","schema":{"type":"string","example":"refreshToken=abc123...; HttpOnly; Secure; SameSite=None"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden - User doesn't have permission to impersonate"},"500":{"description":"Internal server error"}}}},"/api/casino/invite":{"post":{"tags":["Casino"],"summary":"Invite a casino","description":"This API sends an invitation to a casino owner.\n\nThe invited user receives a registration link.\n\n**Required fields:**\n* **name**\n* **email**\n\n**Optional fields:**\n* **location**\n\n**Validation Rules:**\n* Email must be unique\n* Casino name cannot be empty\n\n**On success:**\n* Invitation email is sent\n* Registration token is generated\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","example":"Royal Casino"},"email":{"type":"string","example":"casino@mail.com"},"location":{"type":"string","example":"Las Vegas"}}},"examples":{"basic":{"summary":"Basic Invite","value":{"name":"Royal Casino","email":"casino@mail.com","location":"Las Vegas"}},"another":{"summary":"Another Casino","value":{"name":"MGM Casino","email":"mgm@mail.com","location":"Nevada"}}}}}},"responses":{"201":{"description":"Casino invited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"description":"Validation error"},"500":{"description":"Internal server error"}}}},"/api/casino/register/{token}":{"post":{"tags":["Casino"],"summary":"Register casino owner","description":"This API registers a casino owner using an invitation token.\n\n**Path Parameter:**\n* **token**\n\n**Required fields:**\n* **name**\n\n**Optional fields:**\n* **phone**\n\n**Validation Rules:**\n* Token must be valid\n* Token must not be expired\n\n**On success:**\n* Casino owner account is activated\n* Casino profile is linked\n","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"John Doe"},"phone":{"type":"string","example":"9876543210"}}},"examples":{"owner1":{"summary":"Casino Admin","value":{"name":"John Doe","phone":"9876543210"}},"owner2":{"summary":"Manager","value":{"name":"Alex Smith","phone":"9999999999"}}}}}},"responses":{"201":{"description":"Casino owner registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object"}}}}}},"400":{"description":"Invalid token or expired invite"},"500":{"description":"Internal server error"}}}},"/api/casino/get-all-casinos":{"get":{"tags":["Casino"],"summary":"Get all casinos","description":"This API retrieves all casinos from the system.\n\nSupports:\n* Pagination\n* Search by casino name, email, or location\n* Sorting\n* Date filtering\n* Dynamic casino filters\n* Dynamic location filters\n\n**Query Parameters:**\n* **page**\n* **limit**\n* **search**\n* **sortBy**\n* **sortOrder**\n* **dateFilter**\n* **casino**\n* **location**\n\n**Supported Date Filters:**\n* TODAY\n* YESTERDAY\n* LAST_7_DAYS\n* LAST_30_DAYS\n\n**Supported Sorting:**\n* name\n* email\n* createdAt\n\n**Security:**\n* Requires authentication\n\n**Role Access:**\n* SUPER_ADMIN can view all casinos\n* Other users may have restricted access based on permissions\n\n**Response Includes:**\n* Casino details\n* Linked casino users\n* Dynamic filter values\n* Pagination metadata\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","example":1}},{"name":"limit","in":"query","schema":{"type":"integer","example":10}},{"name":"search","in":"query","schema":{"type":"string","example":"royal"}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","email","createdAt"],"example":"createdAt"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"dateFilter","in":"query","schema":{"type":"string","enum":["TODAY","YESTERDAY","LAST_7_DAYS","LAST_30_DAYS"],"example":"LAST_7_DAYS"}},{"name":"casino","in":"query","schema":{"type":"string","example":"Royal Casino"}},{"name":"location","in":"query","schema":{"type":"string","example":"Las Vegas"}}],"responses":{"200":{"description":"Casino list fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"status":{"type":"string"},"totalAmount":{"type":"number"},"createdAt":{"type":"string"},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"status":{"type":"string"}}}}}}},"filters":{"type":"object","properties":{"casinos":{"type":"array","items":{"type":"string"},"example":["ALL","Royal Casino","MGM Casino"]},"locations":{"type":"array","items":{"type":"string"},"example":["ALL","Las Vegas","Nevada"]}}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"total":{"type":"integer","example":25},"totalPages":{"type":"integer","example":3},"hasNextPage":{"type":"boolean","example":true},"hasPrevPage":{"type":"boolean","example":false}}}}}}}},"500":{"description":"Failed to fetch casinos"}}}},"/api/casino/get-casino-by-id/{id}":{"get":{"tags":["Casino"],"summary":"Get casino by ID","description":"This API retrieves detailed information about a specific casino.\n\n**Path Parameter:**\n* **id** - Casino ID\n\n**Security:**\n* Requires authentication\n\n**Response Includes:**\n* Casino details\n* Linked users\n* Casino status\n* Total amount\n* Created date\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Casino fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"Casino not found"}}}},"/api/casino/update-casino/{casinoId}":{"patch":{"tags":["Casino"],"summary":"Update casino","description":"This API updates casino information.\n\n**Path Parameter:**\n* **casinoId**\n\n**Updatable Fields:**\n* name\n* email\n* location\n* status\n\n**Security:**\n* Requires authentication\n* Requires update permission\n\n**Validation Rules:**\n* Casino must exist\n* Email must be unique if updated\n\n**On success:**\n* Casino details are updated successfully\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"casinoId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Royal Casino"},"email":{"type":"string","example":"royalcasino@mail.com"},"location":{"type":"string","example":"Las Vegas"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MAINTENANCE"]}}}}}},"responses":{"200":{"description":"Casino updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Casino updated successfully"},"data":{"type":"object"}}}}}},"400":{"description":"Casino update failed"},"404":{"description":"Casino not found"}}}}}}