A tenant is one isolated environment within your organisation — a sub-unit holding its own users, applications, configuration, and traffic boundary. Tenants move through a small, well-defined set of states; the control plane runs a workflow that takes them between those states and the platform refuses transitions that aren't on the table below.
One tenant per sub-unit
A common shape: one tenant per product line + one tenant per environment within each line. A Cymmetri-style org might have banking-prod, banking-staging, health-prod. Tenants are designed to be plentiful; spin them up when separation is useful.
The six states
A tenant is always in exactly one of these states:
Pending — the row has been created in the control plane database, but the provisioning workflow has not started yet.
Provisioning — the platform is allocating the tenant's resources. Typically 30 seconds to a few minutes depending on plan tier.
Active — provisioning succeeded; the tenant is serving authentication traffic at its subdomain.
Suspended — an administrator has paused traffic; the tenant's resources still exist but reject auth requests.
Decommissioned — resources have been released. The tenant's slug can be recreated.
Failed — provisioning rolled back. The tenant is retryable from this state.
Valid transitions
Not every state can move to every other state. The platform enforces the transition table — invalid moves are refused before they touch a tenant's resources.
From | Allowed next states |
|---|---|
pending | provisioning, failed |
provisioning | active, failed |
failed | provisioning, decommissioned |
active | suspended, decommissioned |
suspended | active, decommissioned |
decommissioned | provisioning (recreate) |
Why decommissioned tenants retain history
Decommissioning a tenant releases its resources but never hard-deletes the record. The tenant remains in the control plane in decommissioned state with its decommissioning timestamp, so historical reports, billing reconciliation, and compliance exports still resolve.
To reuse the same slug for a new tenant, transition from decommissioned back to provisioning — the platform allocates fresh resources under the same name.
Where the transitions are emitted
Every state change emits an OrgEvent to the org-scoped audit log. Operators inspecting "what happened to this tenant" can read the chronology from the CP audit page.