Suspend vs revoke for self-hosted product licenses

Self-hosted Hesabi instances report license status from the DarDev License Control Plane on every heartbeat. Operators and cloud superadmin can patch instance status to suspend or revoke—but the two actions mean different things for end users, JWT validity, and recovery workflow. Choosing wrong creates either unnecessary re-activation friction or a instance that still reads data when it should be fully offline.

Suspend is read-only mode: the instance keeps its activation key and license JWT, shows a maintenance or payment banner, and blocks writes while allowing audit exports in many configurations. Revoke is hard termination: activation is cleared, instance token invalidated, and the deployment must activate again with a new key from cloud superadmin. The license-control-plane-go-sqlite guide covers the Go service and SQLite model behind both paths.

Status lifecycle overview

Normal operation is ACTIVE. Missed heartbeats trigger automated GRACE then SUSPENDED via background sweep on the license server—fifteen minute ticker without operator action. Operators can also set SUSPENDED or REVOKED explicitly through ops API or admin HTML. REACTIVATION from suspend returns to ACTIVE when heartbeat resumes and patch clears manual flag.

1. ACTIVE — full read and write per plan entitlements
2. GRACE — heartbeat lag warning window before suspend
3. SUSPENDED — read-only; JWT often still valid with status flag
4. REVOKED — activation consumed or invalidated; must re-activate

Suspend: read-only with banner

Use suspend when the customer relationship is paused—not ended. Examples: overdue invoice negotiation, contract renewal in progress, temporary compliance hold, or platform maintenance requiring no writes without wiping instance identity.

Hesabi self-hosted-instance-guard reads license JWT status on each request. SUSPENDED shows banner text from remote_config—French, Arabic, English maintenance strings—and blocks create and update routes while allowing read-only navigation in many modules. Instance token and activation key remain in local license-store; heartbeat continues reporting suspended state so operators see last contact in admin UI.

Recovery: patch instance status back to ACTIVE in license admin or resolve billing in cloud superadmin; next successful heartbeat delivers updated JWT and configVersion. No new activation key email required if key was not revoked.

Revoke: clear key and force re-activation

Use revoke when the instance must stop trusting current credentials entirely. Examples: customer churn with data export completed, fraudulent activation, hardware fingerprint change policy requiring fresh key, or migration to new self-hosted host where old instance should not resurrect.

Revoke marks activation used or revoked, invalidates instance token hash, and sets status REVOKED. Hesabi guard clears or rejects stored JWT; setup flow redirects toward /setup re-activation with new key from superadmin—not merely a read-only banner. Heartbeat from old token fails authentication.

Side-by-side comparison

• Activation key — suspend: kept; revoke: cleared or marked unusable
• License JWT — suspend: often still present with status SUSPENDED; revoke: invalid or cleared locally
• User experience — suspend: banner plus read-only; revoke: setup redirect re-activation
• Heartbeat — suspend: continues; revoke: fails auth on old token
• Recovery effort — suspend: patch ACTIVE; revoke: issue new key and activate
• Typical owner — finance pause vs security or churn offboarding

Automated vs manual suspend

Automated sweep: missed heartbeats move ACTIVE to GRACE to SUSPENDED without human click—protects against ghost instances that stopped reporting. Manual suspend: operator action via PATCH /v1/solutions/hesabi/instances/{id} or admin HTML button for immediate read-only before sweep timer.

Automated suspend is reversible by fixing heartbeat connectivity—instance regains ACTIVE when posts resume and grace clears. Manual suspend may include remote_config banner explaining payment contact—remote_config PATCH is per solution_id on license plane.

What cloud superadmin sees

Hesabi cloud superadmin self-hosted-instances page proxies ops API with solution-scoped credentials—never exposed to self-hosted deployments. Operators see status, last heartbeat, plan, and actions suspend, renew, revoke. DarDev platform admin HTML at licence host duplicates break-glass controls for infrastructure team.

DarDev Ops links deploy and health only—no daily license operations in Ops Configure. multi-product-saas-one-core describes edition gates: cloud default unaffected; self-hosted gates on DEPLOYMENT_MODE=self-hosted only.

Hesabi app behavior summary

Suspend: banner from remote_config, write operations blocked, reads allowed per guard rules, JWT may remain until expiry but status field enforces policy. Revoke: key cleared from secure store, user directed to activation flow, no silent read-only continuation.

Heartbeat scheduler keeps posting metrics during suspend so operators see orgCount and version—useful for support calls while billing resolves. After revoke, scheduler stops successfully authenticating until new activate flow completes.

Operator decision guide

1. Payment late but customer communicating — suspend with banner pointing to billing contact
2. Trial ended, customer may return — suspend first; revoke after retention window
3. Contract ended, data exported — revoke and archive activation record
4. Suspected key leak — revoke immediately; issue new key to legitimate host fingerprint
5. Instance cloned without approval — revoke old fingerprint; suspend clone if identified before revoke

Document actions in license_events audit—activated, heartbeat, suspended, revoked timestamps support support tickets without exposing internal IDs in customer-facing news.