Unified SSO & Billing Architecture

This document describes the target architecture for WaZoBia OS unified identity and billing — the foundation for a true multi-product business platform (Zoho-style "one account, many apps").

Current state (July 2026)

Pain points:

• Users register separately per product
• No shared customer graph or org/tenant model
• Enterprise deals require manual coordination across apps
• Partner commissions and product subscriptions are siloed

Target state

One WaZoBia identity per person and one organisation (tenant) per business, with:

1. Single sign-on (SSO) — sign in once at wazobiaos.com or any product app; access all entitled products
2. Unified billing — one subscription or bundle (e.g. "WaZoBia Business") with product entitlements
3. Shared org model — branches, roles, and team invites work across products
4. Central audit trail — login events, billing changes, and admin actions logged per tenant

Recommended architecture

Option A — Managed IdP (fastest MVP)

Use Clerk, Auth0, or Firebase Auth with:

• Organisations / multi-tenant support
• Social + email/password + magic links
• JWT issued to each product app with org_id and product_entitlements claims

Pros: Speed to market, MFA, compliance helpers
Cons: Cost at scale, vendor lock-in, custom partner-portal flows still need work

Option B — Custom identity service (recommended long-term)

Build WaZoBia Identity as a dedicated service:

Token claims example:

{
  "sub": "user_abc",
  "org_id": "org_xyz",
  "email": "owner@business.ng",
  "roles": ["owner"],
  "products": ["invoice", "books"],
  "plan": "business"
}

Each product app validates JWT (JWKS endpoint) and enforces entitlements locally.

Billing service

Central Billing API responsible for:

• Plan catalog (Starter, Business, Enterprise, à la carte products)
• Subscription lifecycle (create, upgrade, cancel, dunning)
• Webhooks from Paystack / Flutterwave (single webhook URL)
• Entitlement sync to Identity (products[] on org)

Invoice already has payment infrastructure — Phase 1 billing can extend Invoice's Redis/DB as source of truth, with Books/Events reading entitlements via API.

Phased rollout

Phase 1 — Identity hub (8–10 weeks)

• WaZoBia Identity service: register, login, logout, password reset
• OS /login becomes real SSO entry (not redirect-only)
• Invoice app accepts Identity JWT (feature flag)
• Shared cookie domain on production DNS
• Migrate existing Invoice users via email match + forced password reset or magic link

Phase 2 — Org & team model (6–8 weeks)

• Organisation entity: name, branches, owner, billing contact
• Invites and roles (owner, admin, member, accountant)
• Books + Events accept same JWT
• Admin portal reads org from Identity API

Phase 3 — Unified billing (8–12 weeks)

• Plan catalog in Billing service
• Bundle SKUs (Invoice Pro + Books Start, etc.)
• Single checkout on OS or Invoice; entitlements propagate within 60s
• Agent/ASP commission rules unchanged initially (Invoice-side)

Phase 4 — Enterprise & compliance (ongoing)

• SAML/OIDC for enterprise IdP federation
• SLA-backed uptime on Identity + Billing
• SOC 2 / NDPR audit pack for enterprise sales

Security requirements

• HTTPS only; HttpOnly, Secure, SameSite=Lax cookies
• Refresh token rotation; revoke on password change
• Rate limiting on login and password reset (already pattern on Invoice APIs)
• No cross-tenant data leaks — every query scoped by org_id
• Partner portals (Admin/Agent/ASP) remain separate auth with stricter MFA for Admin

Open decisions

Related links

• Enterprise sales — custom agreements and early SSO access
• Security & trust — current payment and data posture
• Help hub — product manuals and FAQs

Questions? Contact hello@wazobiaos.com or your enterprise success manager.