{ "openapi": "3.0.3", "info": { "title": "Hire7 Master Middle Layer Auth & Synchronization Hub API", "description": "Interactive API Documentation & Testing Console for Hire7 Multi-Tenant Authentication, Carrier Credential Vault, and Cross-Module Synchronization Engine (Fuel Management System & Safety Module).", "version": "1.0.0", "contact": { "name": "Hire7 Engineering", "email": "admin@hire7express.com" } }, "servers": [ { "url": "http://localhost:3005", "description": "Local Hire7 Master Hub (Port 3005)" } ], "tags": [ { "name": "Authentication & Identity", "description": "Universal master login, 2FA OTP verification, self-registration, and SSO cross-switching." }, { "name": "Carrier Multi-Tenant Vault", "description": "Isolated carrier fleet login, dynamic module access governance (grant/revoke), and driver deactivation." }, { "name": "Multi-Database Synchronization", "description": "Real-time encrypted onboarding hooks (AES-256-GCM), global batch sync, provisioning, and rollback." }, { "name": "System & Health", "description": "Health check and module status." } ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "paths": { "/api/v1/auth/login": { "post": { "tags": ["Authentication & Identity"], "summary": "Initiate Master Universal Login (Step 1)", "description": "Validates universal user identity via email, username, or phone and dispatches 6-digit 2FA SMS OTP to the enforced mobile destination (+1 406 858 3686).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["identifier", "password"], "properties": { "identifier": { "type": "string", "example": "dhanushka.fiver.lk@gmail.com" }, "password": { "type": "string", "example": "Danu1212@" }, "prefer2fa": { "type": "string", "enum": ["SMS", "EMAIL"], "example": "SMS" } } } } } }, "responses": { "200": { "description": "2FA OTP successfully dispatched.", "content": { "application/json": { "example": { "success": true, "requiresOtp": true, "tempToken": "vt_1790761768113_8144...", "channel": "SMS", "destination": "+140******686", "userId": 2, "globalUserId": "H7-SAF-ADM-2", "message": "A 6-digit verification code has been dispatched to your SMS." } } } }, "401": { "description": "Invalid credentials or user not found." } } } }, "/api/v1/auth/verify-login-otp": { "post": { "tags": ["Authentication & Identity"], "summary": "Verify 2FA Login OTP and Issue Master Token", "description": "Validates the 6-digit verification code sent via SMS/Email and issues a signed Master JWT token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tempToken", "otpCode"], "properties": { "tempToken": { "type": "string", "example": "vt_1790761768113_8144..." }, "otpCode": { "type": "string", "example": "123456" } } } } } }, "responses": { "200": { "description": "Master identity verified successfully.", "content": { "application/json": { "example": { "success": true, "token": "eyJh...", "user": { "id": 2, "globalUserId": "H7-SAF-ADM-2", "email": "dhanushka.fiver.lk@gmail.com", "fullName": "Dhanushka Test", "role": "DRIVER", "allowedModules": ["FUEL", "SAFETY"] } } } } }, "400": { "description": "Invalid or expired OTP code." } } } }, "/api/v1/auth/cross-auth": { "post": { "tags": ["Authentication & Identity"], "summary": "Cross-Module SSO Switching Authorization (Rule 5)", "description": "Requests an SSO handoff token to switch between Fuel and Safety modules without re-entering credentials.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["carrierId", "userId", "sourceModule", "targetModule"], "properties": { "carrierId": { "type": "string", "example": "126" }, "userId": { "type": "integer", "example": 2 }, "sourceModule": { "type": "string", "enum": ["FUEL", "SAFETY"], "example": "FUEL" }, "targetModule": { "type": "string", "enum": ["FUEL", "SAFETY"], "example": "SAFETY" } } } } } }, "responses": { "200": { "description": "Switching authorized. Returns single-use SSO token.", "content": { "application/json": { "example": { "success": true, "accessGranted": true, "ssoToken": "sso_1790761614182_03e8...", "launchUrl": "http://10.0.2.2:3001/api/v1/sso/consume?token=sso_...", "message": "Access to SAFETY module verified and authorized by Carrier 126." } } } }, "403": { "description": "Carrier module access denied or entitlement revoked." } } } }, "/api/v1/auth/sso/consume": { "get": { "tags": ["Authentication & Identity"], "summary": "Consume Single-Use SSO Token", "description": "Consumes a short-lived SSO handoff token and returns the authenticated user session.", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "example": "sso_1790761614182_03e8..." } ], "responses": { "200": { "description": "Token valid and session returned." }, "401": { "description": "Token invalid or expired." } } } }, "/api/v1/carriers": { "get": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "List All Registered Carriers & Module Subscriptions", "description": "Returns all registered carrier tenants along with their active module subscriptions (Fuel, Safety, or Both).", "responses": { "200": { "description": "List of carriers.", "content": { "application/json": { "example": { "success": true, "count": 4, "carriers": [ { "carrierId": "1", "carrierName": "Northline Freight Systems Inc.", "subscribedModules": ["SAFETY", "FUEL"] }, { "carrierId": "126", "carrierName": "prathibha", "subscribedModules": ["FUEL", "SAFETY"] } ] } } } } } } }, "/api/v1/carriers/{carrierId}/status": { "get": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "Get Carrier Status & Module Subscriptions", "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "126" } ], "responses": { "200": { "description": "Carrier status details." } } } }, "/api/v1/carriers/{carrierId}/login": { "post": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "Isolated Carrier Fleet Vault Login (Rule 2)", "description": "Authenticates driver into an isolated carrier fleet using the carrier-specific PIN or Password without requiring a second OTP.", "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "126" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["identifier", "pin"], "properties": { "identifier": { "type": "string", "example": "dhanushka.fiver.lk@gmail.com" }, "pin": { "type": "string", "example": "1212" }, "password": { "type": "string", "example": "Danu1212@" } } } } } }, "responses": { "200": { "description": "Carrier vault authentication successful.", "content": { "application/json": { "example": { "success": true, "carrierToken": "eyJh...", "activeCarrier": { "carrierId": "126", "carrierName": "prathibha" }, "driver": { "userId": 2, "globalUserId": "H7-SAF-ADM-2", "allowedModules": ["FUEL", "SAFETY"] } } } } }, "401": { "description": "Carrier credential check failed (Rule 2 isolation)." } } } }, "/api/v1/carriers/{carrierId}/drivers": { "get": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "List Drivers Under Carrier Fleet", "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "126" } ], "responses": { "200": { "description": "List of drivers with active entitlements." } } } }, "/api/v1/carriers/{carrierId}/drivers/{userId}/module-access": { "post": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "Carrier Admin Grant or Revoke Driver Module Access (Rule 4)", "description": "Allows a Carrier Administrator to dynamically grant or revoke access to Fuel or Safety modules.", "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "126" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 2 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["moduleCode", "action"], "properties": { "moduleCode": { "type": "string", "enum": ["FUEL", "SAFETY"], "example": "SAFETY" }, "action": { "type": "string", "enum": ["GRANT", "REVOKE"], "example": "GRANT" }, "notes": { "type": "string", "example": "Approved by fleet administrator" } } } } } }, "responses": { "200": { "description": "Module access successfully updated." } } } }, "/api/v1/carriers/{carrierId}/drivers/{userId}/deactivate": { "post": { "tags": ["Carrier Multi-Tenant Vault"], "summary": "Deactivate Driver Under Carrier Fleet", "description": "Completely deactivates the driver under the carrier and revokes all module entitlements.", "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "126" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "Driver left company" } } } } } }, "responses": { "200": { "description": "Driver deactivated." } } } }, "/api/v1/sync/status": { "get": { "tags": ["Multi-Database Synchronization"], "summary": "Get Multi-Database Synchronization Matrix & KPI", "description": "Returns counts of master users, origin breakdown (Safety vs Fuel), module grants, cross-module users, and sync status matrix.", "responses": { "200": { "description": "Multi-database sync status.", "content": { "application/json": { "example": { "totalUsers": 36, "originStats": { "SAFETY": 32, "FUEL": 3, "PORTAL_SELF_REG": 1 }, "crossModuleUsers": 4, "syncMatrix": { "SAFETY": { "SYNCED": 35 }, "FUEL": { "SYNCED": 4 } } } } } } } } }, "/api/v1/sync/trigger": { "post": { "tags": ["Multi-Database Synchronization"], "summary": "Trigger Global Multi-Database Sync Pass", "description": "Scans all drivers across Fuel and Safety module databases and synchronizes newly added or updated profiles into the Hire7 Master directory.", "responses": { "200": { "description": "Sync pass completed.", "content": { "application/json": { "example": { "success": true, "message": "Global multi-database sync pass completed successfully.", "summary": { "safety": { "importedUsers": 0, "importedDrivers": 0 }, "fuel": { "importedDrivers": 0 } } } } } } } } }, "/api/v1/sync/encrypt-payload-helper": { "post": { "tags": ["Multi-Database Synchronization"], "summary": "Helper: Encrypt Driver Registration Payload (AES-256-GCM)", "description": "Development and integration helper that encrypts driver onboarding data into AES-256-GCM ciphertext + HMAC signature for safe wire transmission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["carrierId", "carrierName", "sourceModule", "driver"], "properties": { "carrierId": { "type": "string", "example": "126" }, "carrierName": { "type": "string", "example": "prathibha" }, "sourceModule": { "type": "string", "example": "FUEL" }, "driver": { "type": "object", "properties": { "carrierDriverId": { "type": "string", "example": "111" }, "firstName": { "type": "string", "example": "Dhanushka" }, "lastName": { "type": "string", "example": "Test" }, "email": { "type": "string", "example": "dhanushka.fiver.lk@gmail.com" }, "phoneNumber": { "type": "string", "example": "4068583686" }, "phoneCountryCode": { "type": "string", "example": "+1" }, "carrierUsername": { "type": "string", "example": "dhanushka.fiver.lk@gmail.com" }, "carrierPassword": { "type": "string", "example": "Danu1212@" }, "carrierPin": { "type": "string", "example": "1212" }, "allowedModules": { "type": "array", "items": { "type": "string" }, "example": ["FUEL", "SAFETY"] } } } } } } } }, "responses": { "200": { "description": "Encrypted payload object containing iv, tag, and ciphertext." } } } }, "/api/v1/sync/onboard-driver": { "post": { "tags": ["Multi-Database Synchronization"], "summary": "Inbound Driver Onboarding Hook (Encrypted - Rule 3)", "description": "Receives AES-256-GCM encrypted driver payload, validates HMAC signature, and provisions driver under carrier multi-tenant isolation.", "parameters": [ { "name": "X-Sync-Module", "in": "header", "required": false, "schema": { "type": "string" }, "example": "FUEL" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["carrierId", "iv", "tag", "ciphertext"], "properties": { "carrierId": { "type": "string", "example": "126" }, "carrierName": { "type": "string", "example": "prathibha" }, "iv": { "type": "string" }, "tag": { "type": "string" }, "ciphertext": { "type": "string" } } } } } }, "responses": { "200": { "description": "Driver successfully onboarded and provisioned." } } } }, "/api/v1/sync/user/{id}": { "post": { "tags": ["Multi-Database Synchronization"], "summary": "Synchronize Driver to Target Module Database", "description": "Manually triggers bidirectional provisioning of a Master User into the target module (Fuel or Safety).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 2 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["targetModule"], "properties": { "targetModule": { "type": "string", "enum": ["FUEL", "SAFETY"], "example": "SAFETY" } } } } } }, "responses": { "200": { "description": "User successfully synchronized to target module." } } } }, "/api/v1/sync/rollback-driver/{id}": { "post": { "tags": ["Multi-Database Synchronization"], "summary": "Rollback Driver Onboarding", "description": "Purges mistaken or partial driver onboarding credentials and entitlements under a carrier.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 32 } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "carrierId": { "type": "string", "example": "126" }, "reason": { "type": "string", "example": "Incorrect details" } } } } } }, "responses": { "200": { "description": "Driver onboarding cleanly rolled back." } } } }, "/api/v1/sync/logs": { "get": { "tags": ["Multi-Database Synchronization"], "summary": "Get Sync Audit Trail Logs", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" }, "example": 20 } ], "responses": { "200": { "description": "Audit trail log records." } } } }, "/api/v1/health": { "get": { "tags": ["System & Health"], "summary": "System Health & Uptime Check", "responses": { "200": { "description": "Service healthy." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter Master Auth JWT Token (or Carrier Token) to lock session for all requests." }, "basicAuth": { "type": "http", "scheme": "basic", "description": "Enter Username (e.g. admin@hire7express.com or clientuser126) and Password (e.g. Abcd@1234 or Danu1212@)." } } } }