Authentication, Workspace Access & Support Impersonation
The security perimeter. Learn how NotifyIQ provisions isolated multi-tenant workspaces, manages role-based access control (RBAC), tracks referral onboarding, and provides zero-password Admin Support Impersonation.
1. Purpose of the Page
NotifyIQ is an enterprise multi-tenant software platform. Every customer operates inside an isolated workspace bounded by their unique workspaceId. This guide explains how users authenticate, how new tenants are registered and attributed to partners, and how authorized platform engineers diagnose tenant issues safely using temporary cryptographically signed impersonation sessions.
2. Who Uses It (Target Roles)
Provisions a brand new company workspace and sets up the primary workspace administrator account.
Logs in with individual credentials to manage WhatsApp chats and handle customer inquiries.
Uses signed one-time impersonation links from the central admin console to assist clients in real time.
Interactive Visual Preview
Super-admins can access client workspaces to debug WABA webhook deliveries or template formatting without requesting client passwords:
3. Step-by-Step: Onboarding and Role Management
- Workspace Registration: Navigate to
/register. Enter your company name, admin email, and secure password (minimum 6 characters). If arriving through an affiliate partner link (?ref=...), partner attribution is automatically preserved. - Standard Sign In: Existing operators sign in at
/login. The backend verifies credentials, returns a JWT token, and establishes the active workspace session. - Role-Based Access Enforcement: Users are assigned either the ADMIN role (access to Billing, API Keys, WABA Credentials, and Team Settings) or the AGENT role (focused purely on Live Inbox care, Contacts, and Campaign dispatching).
- Admin Support Impersonation: When an enterprise client requests assistance, certified super-admins can click “Access Workspace” from the central Admin Console. This opens
/auth/admin-impersonation?token=...&workspace=..., validating the temporary support token and mounting the workspace session with full audit logging.
4. Authentication Security & Token Headers
| Header / Property | Storage Key | Payload Format | Purpose |
|---|---|---|---|
| Authorization | notifyiq_token | Bearer <JWT> | Cryptographically signed JSON Web Token verifying user identity and roles. |
| x-workspace-id | notifyiq_workspace | MongoDB ObjectId string | Enforces strict database tenancy, preventing cross-tenant data leakage. |
| Impersonation Token | URL param 'token' | Signed 15-min JWT | Single-use token issued exclusively to super-admins with audit logging. |
5. Behind the Scenes: Multi-Tenant Database Isolation
Tenant security is enforced at the database query layer:
- Automatic Query Scoping: Every database query for contacts, messages, templates, and flows includes an immutable filter:
{ workspaceId: req.user.workspaceId }. - Password Hashing: User passwords are encrypted using bcrypt with high work factors before ever being persisted.
- Impersonation Audit Trail: Every action taken during an impersonated support session is tagged in audit logs with both the super-admin operator ID and the target workspace ID.
6. Common Errors & FAQs
Standard operator sessions remain valid for 7 days unless explicitly logged out. Impersonated support tokens expire automatically after 15 minutes.
No. Multi-tenant isolation strictly segments all data. Contacts, messages, WABA tokens, and billing records are completely isolated by workspace ID.