License tokens

Every bootable AVERASE stick carries one license token — the single object that decides whether that stick may unlock, report hardware, and wipe. This page covers what a token is, its statuses and exactly what each blocks, quota, day-to-day management, and what the operator sees when a device is denied.

What a token is

A license token is minted every time an admin downloads an ISO from /downloads, and is spliced into that ISO as it streams down — the stick arrives already bound to your account. Technically it is a compact Ed25519 JWS (header {"alg": "EdDSA", "typ": "JWT"}) with four claims:

The signature proves only that AVERASE minted the token. Entitlement — status, quota, subscription — is checked server-side on every call, so a token that was valid yesterday can be dead today. The server-side record (ltok_…) additionally carries the product (engine or hotswap), status, quota_limit, use_count, and last_seen_at.

Statuses and what each blocks

A token is in exactly one of four statuses. Two further deny reasons — account_inactive and quota_exceeded — apply to tokens that are otherwise active.

Status / condition	Boot verify	Pre-wipe check-in	Wipe results, asset reports, tests, notes	Who can undo it
active	Allowed	Allowed	Allowed	—
suspended	Denied	Denied	Denied (403 token suspended)	Account admin (Reinstate)
revoked	Denied	Denied	Denied (403 token revoked)	Account admin (Reinstate)
disabled	Denied	Denied	Denied (403 token disabled)	MAESON staff only
account_inactive (subscription lapsed)	Denied	Denied	Allowed	Renew the subscription
quota_exceeded	Denied	Denied	Allowed	Account admin / new token

The distinction in the third column matters: a suspended, revoked, or disabled token is dead for everything, while an out-of-quota or lapsed-subscription stick can still deliver the results of wipes it already performed — it just can't unlock or start new ones.

The decision order

Every verify and check-in walks the same ordered decision, and the first match wins:

1. disabled — the staff kill switch, outranks everything
2. revoked
3. suspended
4. account_inactive — unless the account has an active subscription
5. quota_exceeded — use_count has reached quota_limit
6. ok — allow

So a token that is both revoked and out of quota reports revoked, and no account-level action can shadow a staff disabled.

Quota

• quota_limit caps how many wipes a token may authorize; null means unlimited. Today every token is minted with quota_limit null — plan-tier quotas are planned but not yet wired, so quota enforcement is live code you won't hit yet.
• use_count is incremented by an atomic SQL update at check-in (POST /internal/tokens/validate) — the only metered call. One check-in happens per erase run.
• Verify is unmetered. Booting a stick any number of times costs nothing; only starting a wipe does.
• The kiosk's Worker popup shows the live balance as "Wipes remaining" — a number, or unlimited.

Managing tokens from /downloads

Token management lives in the ISO control column of /downloads (account admins only) — there is no separate token index page. It lists up to 200 tokens, newest first. Each row shows the token id (ltok_…), a status badge — Active (green), Suspended (yellow), Revoked (red), Disabled (solid) — plus Product, Issued to, Wipes used (use_count of quota_limit, or ∞), Last seen, and Issued. Before any download the column reads "No device tokens issued yet. Download an ISO to mint one."

The actions depend on status:

• Active → Suspend and Revoke. Revoke confirms first: "Revoking is permanent for this token. Continue?" (Permanent in intent — an admin can still Reinstate, but treat revoke as end-of-life and reissue instead.)
• Suspended or Revoked → Reinstate.
• Disabled → no actions; the row notes "Disabled by MAESON support — contact support to restore."

A status change takes effect on the stick's next contact — its next boot verify or pre-wipe check-in is denied. There is no way to interrupt a wipe already in progress from the web app.

The MAESON staff kill switch

The fourth status, disabled, is reserved for MAESON Technologies staff. It records who disabled the token, when, and why; it outranks every other status in the decision order; and the account's own admins cannot revoke, suspend, or reinstate around it — those actions are refused while a token is staff-disabled. If one of your tokens shows Disabled, contact support.

What a denied device shows the operator

A denied stick is not silent — the kiosk maps each wire-level deny reason to an operator message. At boot the message appears in the Worker popup; at wipe time it appears in a modal titled Wipe blocked as Wipe denied: {reason}.

Deny reason	Operator message
disabled	This ISO has been disabled by MAESON support. Contact support — your account admin cannot re-enable it.
revoked	This device's licence was revoked by an account admin. Download a fresh ISO.
suspended	This device's licence is suspended. An account admin can reinstate it.
quota_exceeded	This device has used its entire wipe quota. Contact your account admin.
account_inactive	The AVERASE subscription for this account is not active. Renew it to keep wiping.
not_found / invalid_token	This stick's licence token is not recognised. Download a fresh ISO.
validation_unavailable	The licence server is unreachable right now. Check the network and try again.
any other reason	Licence check denied ({other}).
network/transport failure	Could not reach the licence server. Check the network and try again. ({error})

A stick whose ISO was never provisioned with a token (for example, a raw image that never went through /downloads) is permanently locked with: "This device is not provisioned: no licence token was found on the USB stick. Download a fresh ISO from your AVERASE account." — and its wipes are blocked with "Device not provisioned: no backend token configured. Wipe blocked."

Note the last two table rows: network failure is a deny. The platform is fail-closed end to end — an offline or unreachable stick never unlocks and never wipes.

What's next?

• Platform architecture — where tokens sit in the full lifecycle
• Downloads — the /downloads page in depth
• Engine boot & licensing — the lock, verify, and unlock flow on the device
• Internal API — the verify and validate endpoints behind the decisions