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.
An external_ref is your own stable handle for a tenant. Every endpoint except create accepts it as an alternative to tenant_id — supply exactly one. create accepts only external_ref, because the tenant does not exist yet and there is no UUID to pass.
The pair (account, external_ref) is the idempotency lock for create: once you provision with a given value, that value is bound to that tenant forever.
Format
Use a <panel>:<id> shape so the source system is obvious at a glance:
| Panel | Example |
|---|---|
| WHMCS | whmcs:1234 |
| Upmind | upmind:acct_abc |
| Custom | custom:org_42 |
The value is scoped per account — the same string can exist under two different platform accounts without collision. It is stored as text; keep it under roughly 200 characters.
Never reuse a value
Do not reuse an external_ref for a different service, even after the original
tenant has been terminated. The mapping is permanent, and reuse will resolve to
the old, now-deleted tenant rather than provisioning a new one.
Prefer external_ref over tenant_id
We strongly recommend calling every endpoint by external_ref rather than caching tenant_id on your side. An external_ref is yours: it survives panel restarts, database migrations, and any internal change to how workspace UUIDs are stored. Caching tenant_id couples your panel to an identifier you do not own.
If you only have a tenant_id and want to confirm a tenant exists, any read or no-op endpoint — for example usage — will resolve it.
Data model
How platform accounts, tenants, and web-host users fit together — and which of them is the billing entity.
WHMCS module
Resell Swarmz from WHMCS with no code. Install the module, set your API key once, create a server, and every WHMCS service lifecycle event provisions, signs in, suspends, and tears down a tenant for you.