Data model
How platform accounts, tenants, and web-host users fit together — and which of them is the billing entity.
The Platform API has three nouns. Understanding how they nest is enough to read every endpoint.
Platform account
The hosting company or reseller — you. The platform account owns the Stripe customer, the contract, the API keys, the white-label theme, and an optional custom domain. It is created by a Swarmz superadmin and is never host-created; see Onboarding.
Its status is one of:
| Status | Meaning |
|---|---|
draft | Created, not yet activated. create and sso return 409 account_inactive. |
active | Fully operational. |
disabled | Authentication itself fails — see Authentication. |
suspended | Account-level hold. |
Tenant (= workspace)
One Swarmz workspace tied to your account — exactly one per service in your panel. A tenant is addressed by tenant_id (the workspace UUID) or by external_ref; every endpoint except create accepts either.
Its lifecycle status is one of:
| Status | Meaning |
|---|---|
active | Normal operation. |
suspended | Reversibly paused — see suspend. |
terminated | Permanently gone — see terminate. |
WHU (web-host user)
Your end customer. A WHU is not a Supabase Auth user. They are identified by a synthetic id that becomes the sub claim on the SSO token, and they are scoped by row-level security so they can never see another tenant's data.
Who pays
The platform account is the billing entity
All real cost — credits and cloud — meters to you, never to the WHU. A WHU never holds a Stripe relationship with Swarmz. Entitlements are a per-customer budget cap, not a funding source: they bound what a tenant may consume, but the bill always flows to your account.
Authentication
Every Platform API call is authenticated by a bearer key scoped to your platform account. Keys are stored as a hash, shown once, and rotated through support.
External references
Address every tenant by your own stable handle instead of caching a workspace UUID. The (account, external_ref) pair is also the idempotency lock on create.