License activation, and why it locks out slowly, not instantly.

Activation is meant to be invisible — a license flows in from Stripe, through install.sh, straight into the dashboard, with no manual paste-in step. This page covers what to check when that path doesn’t look right.

This page explains how WarmHawk license activation works end to end: the license passed via --license during install, no separate dashboard paste-in step, what “invalid” or “expired” errors mean, how the dashboard’s daily check both re-validates and self-refreshes the license at renewal, and what to do if a real payment succeeded but the dashboard still shows unlicensed.

How activation is supposed to work

Your license key is issued the moment your Stripe checkout completes, and you pass it directly into the install command:

curl -fsSL https://warmhawk.com/install | bash -s -- \
  --license <token-from-your-purchase-email> \
  --domain yourcompany.com \
  --owner-email you@yourcompany.com

Pass your bare company domain — the installer derives api.yourcompany.com for the engine and dashboard.yourcompany.com for the dashboard, and wires the two together for you.

install.sh writes that token into your instance’s .env and the dashboard’s activation flow reads it from there on first boot — there is no separate “paste your license here” screen anywhere in the product. If activation looks broken, the license itself, or the path it took to get here, is what to check.

What “invalid” and “expired” actually mean

The dashboard’s LicenseGate distinguishes two failure states, and they point at different problems:

• License invalid — the token’s RSA signature doesn’t verify. In order of how often it’s actually the cause: the short whk_live_ identifier was pasted instead of the full token; the token was truncated when copied (it’s long, and terminals wrap it); or it belongs to a different environment than the instance you’re installing. Compare the exact string against your confirmation email.
• License expired — the signature is valid, but the embedded expiry timestamp has passed. This is the expected, working state for a subscription that lapsed — not a bug. If your subscription is still active, it just means your instance is holding last period’s token; use Refresh license in the dashboard, covered below.

How LicenseGate’s daily re-validation works

Every license has an expiry embedded in it at issuance, tied to the current Stripe billing period. LicenseGate checks the current time against that embedded expiry, and attempts a refresh, roughly once a day — not on every page load, and it does not actively revoke anything the moment a payment fails.

Between those daily checks, the gate is reading a signed token on your own disk. Your dashboard keeps working through a WarmHawk outage or a network partition — there is no license server your instance depends on to stay up minute to minute.

In practice this means a lapsed subscription locks the dashboard out naturally at its embedded expiry date, on the next daily check — not the instant a card is declined. That’s deliberate: it avoids a jarring mid-session lockout over a same-day billing hiccup, while still guaranteeing access stops within about a day of a subscription actually ending.

Renewals: your license refreshes itself

A monthly license carries about a month of expiry, and an annual one about a year. That expiry is baked in at issuance, so every renewal has to put a new token on your instance — which would be a monthly SSH session if you had to do it by hand. You don’t.

Your dashboard checks in once a day, presents the token it already holds as proof of who it is, and gets back a freshly signed one as long as your subscription is still paying. In the normal case a renewal is invisible: the card charges, the next daily check picks up the new token, nobody touches a server.

• To force it immediately — rather than waiting for the daily check — click Refresh license, on the expired-license screen and under Settings → Billing.
• An expired token still works to refresh with. That is the whole point: a locked-out dashboard is holding an expired token by definition, so being locked out never blocks you from recovering.
• If the subscription genuinely isn’t paying, the refresh declines and tells you so, rather than silently reissuing. Fix the payment method in billing, then refresh again.

Your tier and expiry are always re-read from Stripe at refresh time — never copied from the old token — so a refresh reflects what you’re actually subscribed to today, including an upgrade or downgrade made since your last one.

Paid, but the dashboard still shows unlicensed

This is almost never a payment problem — it’s a webhook delivery problem. Your Stripe checkout succeeding and your license actually reaching your instance are two separate steps connected by a webhook, and that webhook can be delayed, retried, or fail to reach the endpoint.

1. Confirm the Stripe checkout actually completed — check your email for a receipt, or the Stripe Customer Portal.
2. Check whether the webhook that issues the license was delivered and processed successfully — see Stripe checkout & webhooks for exactly what to look for in the Stripe Dashboard’s webhook delivery log.
3. If the webhook shows as delivered and succeeded but activation still fails, email support@warmhawk.com with your Stripe receipt or customer ID.

Still stuck? Contact support

If you’ve confirmed payment succeeded and webhook delivery looks fine but activation still won’t go through, email support@warmhawk.com with your Stripe receipt and the exact error text shown in the dashboard. Support is founder-staffed: expect a response within 1 business day, or 4 business hours for a production instance that’s fully locked out.