Auth System Reference

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/
npm start        # Run dist/server.js
npm run dev      # ts-node with watch (development)