Auth System Reference

⚠️ This doc may be outdated. Last verified: 2025-02-14. The three-tier role model, JWT flow, and /auth, /admin, /superadmin mount prefixes are still accurate, but the route tables below are partial — the live auth.routes.ts also exposes /auth/customer/signup, /auth/public/signup, /auth/change-password, OTP (/auth/public/send-otp, /auth/public/verify-otp), and the email flows (/auth/verify-token, /auth/setup-password, /auth/verify-email, /auth/forgot-password, /auth/resend-verification). For feature/role gating, TEAM-RBAC.md and FEATURE-ENTITLEMENTS-AND-BUNDLES.md are the canonical references.

Architecture

Three-tier role hierarchy: SuperAdmin → Admin → Customer

• SuperAdmin: manages the entire platform (orgs, admins)
• Admin: owns an organization, manages customers
• Customer: uses the Oktivo platform (campaigns, agents, calls)

Every document is scoped by organizationId to prevent cross-tenant data leaks.

Auth Flow

Login → JWT access token (15m) + refresh token (7d)
Request → Authorization: Bearer <accessToken>
401 → Client sends refresh token → New token pair
Refresh fails → Redirect to /login

API Routes

Auth (no JWT required)

Method	Path	Description
POST	/auth/login	Universal login (all roles)
POST	/auth/admin/signup	Admin self-signup with org creation
POST	/auth/refresh	Refresh token pair

Auth (JWT required)

Method	Path	Description
POST	/auth/logout	Invalidate session
GET	/auth/me	Current user + organization info

Admin Routes (JWT + admin role)

Method	Path	Description
GET	/admin/customers	List org customers (paginated)
GET	/admin/customers/:id	Get customer detail
POST	/admin/customers	Create customer
PUT	/admin/customers/:id	Update customer
PUT	/admin/customers/:id/reset-password	Reset customer password
GET	/admin/organization	Get org info + stats
PUT	/admin/organization/branding	Update org branding

SuperAdmin Routes (JWT + superadmin role)

Method	Path	Description
GET	/superadmin/dashboard	Platform-wide stats
GET	/superadmin/organizations	List all orgs (paginated)
GET	/superadmin/organizations/:id	Org detail
POST	/superadmin/organizations	Create org + admin
PUT	/superadmin/organizations/:id	Update org

Campaign System (JWT required, mounted at root /)

Method	Path	Description
POST	/upload-campaign	Upload campaign with CSV
GET	/campaigns	List user's campaigns
GET	/campaigns/:id	Get campaign details
DELETE	/campaigns/:uid	Delete campaign
POST	/start-campaign/:uid	Start campaign
POST	/stop-campaign/:uid	Stop campaign
POST	/create-agent	Create agent
PUT	/update-agent/:id	Update agent
DELETE	/delete-agent/:id	Delete agent
POST	/test-agent	Test call agent
GET	/campaign-detail/:id	Full campaign detail with contacts
GET	/call-summary/:phone/:uid/:contactUID	Call summary
GET	/export-campaign/:id	CSV export
GET	/export-campaign-full/:id	Full export
GET	/recording/:phone/:id	Recording signed URL

Webhooks (no JWT called by external services)

Method	Path	Description
POST	/webhook/call-status	Call status update
POST	/webhook/call-voice	Voice recording webhook

JWT Payload

{
  userId: string;       // MongoDB _id
  role: "superadmin" | "admin" | "customer";
  organizationId: string;  // null for superadmin
}

After verifyJwt middleware, these are available as req.userId, req.role, req.organizationId.

Entry Point

• Source: src/server.ts
• Compiled: dist/server.js
• No more index.js single TypeScript entry point

Build & Run

npm run build    # Compile TS → dist/ (also copies src/widget)
npm start        # Run dist/server.js
npm run dev      # Compile then run dist/server.js (development)