Businesses (tenants)#

Every client on the platform is a business (internally a tenant). The Businesses screen at /super-admin/tenants is where you create them, hand over the admin login, watch subscription state, and — when needed — suspend or impersonate one.

Who this is for#

Super Admins. Creating a business also creates that client's admin user, so read the hand-over options carefully.

• Difficulty: Medium
• Time: 10 min
• Prerequisites: Super Admin access, and the client's admin name + email ready.

Step 1 — Create a business#

1. Open Businesses → click New business (top right).
2. Fill Workspace Details:
   • Name — the client's company name. The URL slug and subdomain are auto-filled from it; you can override the slug (reserved words are rejected).
   • Max seats — the hard cap on team members (default 5).
   • Plan — pick the plan the client is on. Choosing a plan auto-fills Trial ends at from the plan's trial_days.
   • Subscription status — Trial / Trial expired / Active (paid) / Cancelled / Expired. Leave it on the default at creation; it is normally driven by the lifecycle jobs afterwards.
3. Fill the Tenant Admin section — this creates the client's first user:
   • Admin name and Admin email.
   • Password setup — choose one:
     • Email the admin a setup link (recommended) — the admin receives a welcome email with a /admin/password-setup/{token} link and sets their own password.
     • Auto-generate + show here — a random 16-character password is generated and shown to you once.
     • Set password now — type a password (at least 10 characters) and pass it to the admin securely.
4. Click Create. The workspace is created, the admin user is created with the tenant admin role and set as owner, and the first-login onboarding wizard is marked pending.
5. Hand over the login details (or the password-setup email flow) to the client.

Step 2 — Read the businesses table#

Each row shows:

Step 3 — Use the row actions#

Step 4 — Inspect WhatsApp health from the edit form#

On an existing business, the edit page has a read-only WhatsApp diagnostics section: connection status, verified name, display phone, WABA ID, last webhook time, automation and template counts, messages sent today and failures. Use it to answer "is this client's WhatsApp healthy?" without logging into their panel.

Expected result#

The business exists in the Businesses list, its admin can log in at /admin, and the row shows the correct plan, seats and status. Impersonation and suspension work from the row menu.

Common mistakes#

• Creating the same business twice. Slugs are unique — a duplicate name usually fails on the slug. Search the list first.
• Expecting "Create user" on the Users page. The owner is created here; the Users page has no create action (see Users & agency team).
• Using subscription status to lock someone out. Use Suspend; the status field is informational.
• Suspending the wrong workspace without a reason. The confirmation stores the reason; always write a clear one.
• Forgetting to press Stop after impersonating. The banner is deliberately visible on every page.

Troubleshooting#

Technical details#

• Resource: App\Filament\SuperAdmin\Resources\TenantResource; UI labels in lang/en/filament/sa_tenants.php.
• Model: App\Models\Tenant (tenants table); "LeadHub HQ" is marked by settings.internal.crm_hq and provisioned by php artisan leadhub:setup-hq-crm.
• TenantResource::impersonateAction(), onboardingAction(), suspend/reactivate actions live on the resource; suspend sends App\Mail\WorkspaceSuspendedMail, disables active, and writes audit tags tenant-management, impersonation.
• Creation: App\Filament\SuperAdmin\Resources\TenantResource\Pages\CreateTenant — attaches the admin role, sets owner_id, seat count 1, calls TenantOnboardingService::markPending(), audit tenant.created_by_sa.
• Status derivation: App\Support\TenantSubscriptionState.
• Subscription enforcement: tenant-side EnforceSubscription middleware → /admin/subscription-required.

Related guides#

• Client delivery playbook
• Client onboarding dashboard
• Users & agency team
• Billing overview
• How guided onboarding works