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
Your own stable handle for a tenant — the idempotency key on create and an accepted fallback lookup afterward. The canonical address is the tenant_id returned by create.