MSSP White-Label & Multi-Tenancy

Architecture

A single HailBytes SAT instance hosts an arbitrary number of organizations. Each organization is a tenant boundary: separate users, groups, campaigns, training, and audit log. MSSP staff cross over via membership in multiple orgs (or via an Impersonate action that's fully audited).

• Each org has its own logo, favicon, primary color, support URL, and email-from name.
• Each org has a configurable seat cap (max active users).
• Reports, certificates, and outbound emails inherit the active org's branding.
• The login page detects which org based on the requested hostname (one tenant per subdomain).

Step 1: Create a Tenant Org

POST /api/organizations/
{
  "name": "Northwind Trading",
  "slug": "northwind",
  "seat_cap": 250,
  "support_url": "https://help.northwind.example.com",
  "host": "northwind.sat.example-mssp.com"
}

Step 2: Apply Branding

# Within the tenant context (X-Org-Id header or active session)
PUT /api/branding
{
  "primary_color":   "#0F4C81",
  "secondary_color": "#F5A623",
  "from_name":       "Northwind Security",
  "support_email":   "security@northwind.example.com"
}

PUT /api/branding/logo            # multipart upload
PUT /api/branding/favicon         # multipart upload

Public assets are served at /api/branding/logo/view and /api/branding/favicon/view — the login page renders these even before authentication so first impressions are branded correctly.

Step 3: Add Members & Scoped Users

POST /api/organizations/{id}/members
{
  "user_id":   42,
  "role":      "admin"     # or "operator", "viewer"
}

# MSSP staff can be members of many orgs; client staff only their own.

Step 4: Provision via SCIM (Optional)

For client tenants on Entra ID or Okta, plug each tenant into SCIM 2.0. The SCIM endpoint is org-scoped via API key; one IdP push targets one org.

Step 5: Wire SSO Per Tenant

Each tenant configures their own SAML or OIDC identity provider. The login page reads the host header, looks up the tenant, and shows that tenant's identity provider button.

Step 6: Generate Per-Tenant Reports

for org_id in $(curl -s -H "Authorization: Bearer $KEY" \
                  https://sat-mssp.example.com:3333/api/organizations/ \
                | jq -r '.[].id'); do
  curl -H "Authorization: Bearer $KEY" \
       -H "Accept: application/pdf" \
       "https://sat-mssp.example.com:3333/api/reports/executive?org_id=$org_id" \
       -o "exec-report-$org_id-$(date +%Y-%m).pdf"
done

Seat-Cap Enforcement

When an org reaches its seat cap, new POST /api/organizations/{id}/members calls return 402 Payment Required and SCIM provisioning fails closed. Raise the cap on the org record to admit more users.

Audit & Impersonation

MSSP staff who need to act inside a client tenant use Impersonate. Every impersonation is logged with the staff member's identity, the target org, and an end timestamp — queryable via /api/audit?action=impersonate.

Next Steps