Decommission a tenant

Decommissioning a tenant runs a deprovisioning workflow that releases every resource the tenant held — workloads, storage, identity store — and transitions the tenant to Decommissioned state. The tenant record itself is retained (with its audit history), but no traffic is served and no resources cost anything.

This is the destructive action

Suspend pauses; decommission releases. Once you decommission, the tenant's data is gone — users, applications, sessions, configuration. The audit trail of when and who did what is preserved, but the operational data isn't recoverable. If you need to bring service back up under the same slug, recreate starts from scratch.

When to decommission

Three legitimate reasons:

Customer churned. They're not coming back. Stop paying for their resources.
Test/staging cleanup. You created a tenant for a demo or load-test and you're done with it.
Slug needs to be reused. Decommission, then recreate with the same slug for a fresh start.

Don't decommission to "free up RAM" temporarily — that's what suspend is for. Don't decommission to fix something — there's no restore path.

The decommission action

From the tenant detail page, the Decommission button lives in the Actions section. Available when the tenant is in Active or Suspended state.

Click it. The platform kicks off the deprovisioning workflow immediately — no confirmation dialog today. (Type-to-confirm friction is a future ergonomic improvement.) The state flips to Decommissioning within a second, then to Decommissioned when the workflow finishes (typically under a minute for a Free-plan tenant).

Click once, wait for the state to flip

The Decommission button stays clickable for a moment after the first click while the page refreshes its view of the tenant. If you click a second time after the saga has already finished, you may see a confusing "tenant not found" message — the tenant was successfully decommissioned the first time, the platform just can't find it under the active-tenants filter any more. Refresh the tenant list to confirm; the row will be there with state Decommissioned (decommissioned tenants are filtered out by default — toggle the filter on the Tenants list to see them).

What the workflow does

Each step is idempotent, so the platform retries individual steps on transient failure without redoing the work. The audit feed shows progress in real time. The high-level phases:

Validate the request. Confirms the tenant is in a state that can be decommissioned and that the caller's role admits the action.
Tear down the tenant's workloads. The services that were serving the tenant's traffic stop and are removed.
Release the tenant's resources. Storage, identity store, and traffic boundary are returned to the pool.
Mark the tenant decommissioned. State flips to decommissioned with a timestamp.
Emit the audit event. The action lands in the org audit log as tenant.deprovisioning.completed.

If a phase fails after retries, the workflow stops and the tenant lands in Failed state with the failing step identified in the audit log. See Recover a stuck provisioning saga for the recovery path — most of the same playbook applies to deprovisioning failures.

What remains after decommission

Two things are retained by design:

The tenant record itself, in decommissioned state with decommissioned_at timestamp. Visible from the Tenants list with a filter (decommissioned tenants are hidden by default).
The org audit log entries for everything that ever happened to this tenant — provisioning, suspension, resumption, decommissioning. Retained per your audit retention policy.

Nothing else. Users, sessions, applications, MFA enrollments — all gone with the resource teardown.

What the audit log shows

A decommission emits a series of events in the org audit feed:

tenant.deprovisioning.started — the action was submitted.
tenant.deprovisioning.step_completed — once per saga phase.
tenant.deprovisioning.completed — the workflow finished cleanly.
Or tenant.deprovisioning.failed if it didn't (with the failing step's name in the details).

These are useful for both compliance audit and post-mortem if something didn't go as planned.